feature(gui) themes + chore(deps) version bump

B14-B42 record the Android review the theme and lifecycle work came out of.
DESIGN-TOKENS.md states what both clients agree on and where each keeps its
copy.

Cargo.lock

@@ -4202,9 +4202,9 @@ checksum = "3d595e54a326bc53c1c197b32d295e14b169e3cfeaa8dc82b529f947fba6bcf5"
 
 [[package]]
 name = "proton-drive-rs"
-version = "0.4.0"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b162681255e296b48ef7261cad899ffb384756e866a1c6d7b7c791cbbc8af3ac"
+checksum = "3abae5e90e6889b120208159eb2c60b332612e5b708fdf3c14287307ce01715d"
 dependencies = [
  "async-trait",
  "base64 0.22.1",
@@ -4229,9 +4229,9 @@ dependencies = [
 
 [[package]]
 name = "proton-sdk"
-version = "0.4.0"
+version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32d9b94ec901edb0e849238ea833121f2fb173308b4927b8aa6b157643fa0a73"
+checksum = "3fa729310c1a66e12bb41b9f5f036c86b9857e76536556052203ffecdb0b44c3"
 dependencies = [
  "aes-gcm 0.11.0",
  "async-trait",
@@ -4262,7 +4262,7 @@ dependencies = [
 
 [[package]]
 name = "pstr-android"
-version = "0.2.0"
+version = "0.4.1"
 dependencies = [
  "android_logger",
  "jni 0.21.1",
@@ -4281,7 +4281,7 @@ dependencies = [
 
 [[package]]
 name = "pstr-app"
-version = "0.2.0"
+version = "0.4.1"
 dependencies = [
  "anyhow",
  "eframe",
@@ -4303,7 +4303,7 @@ dependencies = [
 
 [[package]]
 name = "pstr-cli"
-version = "0.2.0"
+version = "0.4.1"
 dependencies = [
  "anyhow",
  "clap",
@@ -4321,7 +4321,7 @@ dependencies = [
 
 [[package]]
 name = "pstr-core"
-version = "0.2.0"
+version = "0.4.1"
 dependencies = [
  "directories",
  "futures",
@@ -4339,7 +4339,7 @@ dependencies = [
 
 [[package]]
 name = "pstr-meta"
-version = "0.2.0"
+version = "0.4.1"
 dependencies = [
  "pstr-core",
  "reqwest",
@@ -4352,12 +4352,13 @@ dependencies = [
 
 [[package]]
 name = "pstr-player"
-version = "0.2.0"
+version = "0.4.1"
 dependencies = [
  "async-trait",
  "libloading",
  "libmpv2",
  "libmpv2-sys",
+ "pstr-core",
  "pstr-stream",
  "thiserror 2.0.19",
  "tokio",
@@ -4366,7 +4367,7 @@ dependencies = [
 
 [[package]]
 name = "pstr-stream"
-version = "0.2.0"
+version = "0.4.1"
 dependencies = [
  "async-trait",
  "futures",

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.2.0"
+version = "0.4.1"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/narrrl/proton-stream"
@@ -28,8 +28,8 @@ authors = ["Nils Pukropp <contact@narl.io>"]
 opt-level = 2
 
 [workspace.dependencies]
-proton-sdk = { version = "0.4.0" }
-proton-drive-rs = { version = "0.4.0" }
+proton-sdk = { version = "0.5.1" }
+proton-drive-rs = { version = "0.5.1" }
 
 # Internal crates.
 pstr-core = { path = "crates/pstr-core" }

README.md

@@ -67,7 +67,7 @@ against the SDK's own range download.
 | Player | Embedded libmpv, drawing into the app's own GL surface: HEVC 10-bit, HDR and ASS subtitles with hardware decode. Volume, audio-track, subtitle and chapter pickers; skip-the-opening; next/previous episode and autoplay. The language picked is preferred for the next file too. |
 | Transcoding | None. mpv demuxes and decodes natively. |
 | UI | egui/eframe on glow; mpv renders into the same GL context. |
-| Themes | The shipped near-black palette plus Catppuccin Latte, Frappé, Macchiato and Mocha, each with a choice of eight accents — pink and sky among them — drawn as a gradient unless you turn that off. Picked on the Shares page, applied without a restart. |
+| Themes | The shipped near-black palette, Catppuccin Latte, Frappé, Macchiato and Mocha, and a Persona 5 one — black, white and one loud red, which is what the Red accent is there for — each with a choice of nine accents, drawn as a gradient unless you turn that off. Picked on the Settings page, applied without a restart. |
 | Metadata | Filename parsing, with optional AniList/TMDB enrichment — **off by default**, because enabling it sends your library's titles to a third party. It brings posters, synopses and per-episode titles; a title the scorer refuses to guess about can be pinned by hand, and a pinned match is never overwritten. |
 | Platforms | Linux and Windows; macOS packaging is written but has not been run on a Mac. A native Android 12+ client is available featuring a Material 3 UI and immersive fullscreen playback. |
 

android/.editorconfig

@@ -0,0 +1,29 @@
+# ktlint configuration.
+#
+# The whole standard ruleset is off, and rules are enabled one at a time. That
+# is deliberate: turning it all on reports ~540 findings on the existing tree,
+# almost all of them line-wrapping preference, and a mechanical reformat of
+# every file would bury the changes that matter in review. The rules kept here
+# are the ones whose violation is a defect or a real maintenance cost rather
+# than a matter of taste — starting with the unused imports that were the
+# evidence no gate ran at all.
+#
+# Adding a rule is cheap. Do it with the reformat it implies in its own commit.
+
+[*.{kt,kts}]
+ktlint_standard = disabled
+ktlint_standard_no-unused-imports = enabled
+ktlint_standard_no-wildcard-imports = enabled
+ktlint_standard_no-semi = enabled
+ktlint_standard_no-trailing-spaces = enabled
+ktlint_standard_no-consecutive-blank-lines = enabled
+ktlint_standard_no-empty-file = enabled
+ktlint_standard_final-newline = enabled
+ktlint_standard_filename = enabled
+ktlint_standard_no-line-break-before-assignment = enabled
+ktlint_standard_no-multi-spaces = enabled
+
+# Vendored from rustls-platform-verifier. Restyling it would turn the next sync
+# with upstream into a merge conflict for no benefit.
+[**/org/rustls/**.kt]
+ktlint = disabled

android/app/build.gradle.kts

@@ -5,6 +5,7 @@ plugins {
     alias(libs.plugins.android.application)
     alias(libs.plugins.kotlin.android)
     alias(libs.plugins.kotlin.compose)
+    alias(libs.plugins.ktlint)
 }
 
 val repositoryRoot = rootProject.projectDir.parentFile
@@ -53,6 +54,7 @@ android {
         targetSdk = 36
         versionCode = releaseVersionCode
         versionName = releaseVersionName
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
 
         ndk {
             abiFilters += listOf("arm64-v8a", "x86_64")
@@ -103,7 +105,51 @@ android {
             isMinifyEnabled = true
             isShrinkResources = true
             if (releaseStore != null) signingConfig = signingConfigs.getByName("release")
-            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+                // Applied to the shipping APK on purpose; the file explains the
+                // trade-off and what each keep is repairing.
+                "proguard-instrumentation.pro",
+            )
+            testProguardFiles("proguard-test-rules.pro")
+        }
+    }
+
+    // The minified path is what ships, and R8 breaks reflective UniFFI/JNA
+    // surfaces in ways no debug run can see. CI sets this to `release` and runs
+    // connectedAndroidTest against it; locally the default keeps builds fast.
+    testBuildType = providers.environmentVariable("ANDROID_TEST_BUILD_TYPE").orNull ?: "debug"
+
+    lint {
+        warningsAsErrors = true
+        abortOnError = true
+        checkDependencies = true
+        // The baseline records what was already here when the gate went in, so
+        // anything *new* fails. It is not a permanent exemption: every entry in
+        // it maps to an open bug in docs/BUGS.md (the SharedPreferences
+        // `commit()` calls are B20, the PiP one is B40), and the file should get
+        // shorter as those land. Regenerate with `gradlew updateLintBaseline`
+        // after a fix, and never to make an unrelated failure go away.
+        baseline = file("lint-baseline.xml")
+        // Generated UniFFI bindings are not ours to fix.
+        disable += setOf("UnusedIds")
+        // Dependency freshness is not a defect, and as errors these break the
+        // gate whenever someone else cuts a release. Upgrades are a deliberate
+        // act with their own verification; `gradlew lintDebug -Dlint...` or a
+        // dependency bot is the right place to surface them, not CI.
+        informational += setOf(
+            "GradleDependency",
+            "NewerVersionAvailable",
+            "AndroidGradlePluginVersion",
+        )
+        sarifReport = true
+    }
+
+    testOptions {
+        unitTests {
+            isIncludeAndroidResources = true
+            isReturnDefaultValues = true
         }
     }
 
@@ -209,7 +255,6 @@ dependencies {
     implementation(libs.androidx.work.runtime)
     implementation(libs.jna) { artifact { type = "aar" } }
 
-
     implementation(platform(libs.androidx.compose.bom))
     implementation(libs.androidx.compose.ui)
     implementation(libs.androidx.compose.ui.tooling.preview)
@@ -219,5 +264,36 @@ dependencies {
     implementation(libs.androidx.compose.material3.adaptive)
     implementation(libs.androidx.compose.material3.navigation.suite)
     debugImplementation(libs.androidx.compose.ui.tooling)
+
     testImplementation(libs.junit)
+    testImplementation(libs.robolectric)
+    testImplementation(libs.androidx.test.core)
+    testImplementation(libs.androidx.work.testing)
+
+    androidTestImplementation(libs.androidx.test.junit)
+    androidTestImplementation(libs.androidx.test.core)
+    androidTestImplementation(libs.androidx.test.runner)
+    androidTestImplementation(libs.androidx.work.testing)
+    androidTestImplementation(platform(libs.androidx.compose.bom))
+    androidTestImplementation(libs.androidx.compose.ui.test.junit4)
+    debugImplementation(libs.androidx.compose.ui.test.manifest)
 }
+
+ktlint {
+    version.set("1.5.0")
+    android.set(true)
+    ignoreFailures.set(false)
+    filter {
+        // UniFFI writes these; they are regenerated on every build.
+        exclude { it.file.path.contains("${File.separator}generated${File.separator}") }
+        // Vendored from rustls-platform-verifier. Restyling it would make the
+        // next sync with upstream a merge conflict for no benefit.
+        exclude { it.file.path.contains("${File.separator}org${File.separator}rustls${File.separator}") }
+    }
+}
+
+// The generated UniFFI directory is a main source dir, so ktlint reads it even
+// though the filter above drops every file in it. Without this, Gradle refuses
+// the build for an undeclared dependency between the two tasks.
+tasks.matching { it.name.startsWith("runKtlintCheckOver") || it.name.startsWith("runKtlintFormatOver") }
+    .configureEach { dependsOn(generateUniFfiBindings) }

android/app/lint-baseline.xml

@@ -0,0 +1,268 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<issues format="6" by="lint 8.13.2" type="baseline" client="gradle" dependencies="true" name="AGP (8.13.2)" variant="all" version="8.13.2">
+
+    <issue
+        id="AndroidGradlePluginVersion"
+        message="A newer version of com.android.application than 8.13.2 is available: 9.3.1"
+        errorLine1="agp = &quot;8.13.2&quot;"
+        errorLine2="      ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="2"
+            column="7"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.compose:compose-bom than 2026.06.00 is available: 2026.06.01"
+        errorLine1="compose-bom = &quot;2026.06.00&quot;"
+        errorLine2="              ~~~~~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="4"
+            column="15"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.activity:activity-compose than 1.11.0 is available: 1.13.0"
+        errorLine1="activity = &quot;1.11.0&quot;"
+        errorLine2="           ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="5"
+            column="12"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.lifecycle:lifecycle-runtime-ktx than 2.9.4 is available: 2.11.0"
+        errorLine1="lifecycle = &quot;2.9.4&quot;"
+        errorLine2="            ~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="6"
+            column="13"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.lifecycle:lifecycle-viewmodel-compose than 2.9.4 is available: 2.11.0"
+        errorLine1="lifecycle = &quot;2.9.4&quot;"
+        errorLine2="            ~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="6"
+            column="13"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.navigation:navigation-compose than 2.9.5 is available: 2.9.8"
+        errorLine1="navigation = &quot;2.9.5&quot;"
+        errorLine2="             ~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="7"
+            column="14"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.work:work-runtime-ktx than 2.10.5 is available: 2.11.2"
+        errorLine1="work = &quot;2.10.5&quot;"
+        errorLine2="       ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="8"
+            column="8"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.work:work-testing than 2.10.5 is available: 2.11.2"
+        errorLine1="work = &quot;2.10.5&quot;"
+        errorLine2="       ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="8"
+            column="8"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.compose.material3.adaptive:adaptive than 1.1.0 is available: 1.2.0"
+        errorLine1="adaptive = &quot;1.1.0&quot;"
+        errorLine2="           ~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="9"
+            column="12"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.compose.material3:material3-adaptive-navigation-suite than 1.1.0 is available: 1.4.0"
+        errorLine1="adaptive = &quot;1.1.0&quot;"
+        errorLine2="           ~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="9"
+            column="12"/>
+    </issue>
+
+    <issue
+        id="GradleDependency"
+        message="A newer version of androidx.core:core-ktx than 1.17.0 is available: 1.19.0"
+        errorLine1="androidx-core = { module = &quot;androidx.core:core-ktx&quot;, version = &quot;1.17.0&quot; }"
+        errorLine2="                                                               ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="19"
+            column="64"/>
+    </issue>
+
+    <issue
+        id="NewerVersionAvailable"
+        message="A newer version of org.jetbrains.kotlin.android than 2.2.21 is available: 2.4.10"
+        errorLine1="kotlin = &quot;2.2.21&quot;"
+        errorLine2="         ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="3"
+            column="10"/>
+    </issue>
+
+    <issue
+        id="NewerVersionAvailable"
+        message="A newer version of org.jetbrains.kotlin.plugin.compose than 2.2.21 is available: 2.4.10"
+        errorLine1="kotlin = &quot;2.2.21&quot;"
+        errorLine2="         ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="3"
+            column="10"/>
+    </issue>
+
+    <issue
+        id="NewerVersionAvailable"
+        message="A newer version of net.java.dev.jna:jna than 5.17.0 is available: 5.19.1"
+        errorLine1="jna = &quot;5.17.0&quot;"
+        errorLine2="      ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="10"
+            column="7"/>
+    </issue>
+
+    <issue
+        id="NewerVersionAvailable"
+        message="A newer version of org.robolectric:robolectric than 4.16 is available: 4.16.1"
+        errorLine1="robolectric = &quot;4.16&quot;"
+        errorLine2="              ~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="12"
+            column="15"/>
+    </issue>
+
+    <issue
+        id="NewerVersionAvailable"
+        message="A newer version of org.jlleitschuh.gradle.ktlint than 13.1.0 is available: 14.2.0"
+        errorLine1="ktlint-plugin = &quot;13.1.0&quot;"
+        errorLine2="                ~~~~~~~~">
+        <location
+            file="../gradle/libs.versions.toml"
+            line="16"
+            column="17"/>
+    </issue>
+
+    <issue
+        id="ObsoleteSdkInt"
+        message="Unnecessary; `SDK_INT` is always >= 31"
+        errorLine1="        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {"
+        errorLine2="            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~">
+        <location
+            file="src/main/kotlin/org/rustls/platformverifier/CertificateVerifier.kt"
+            line="294"
+            column="13"/>
+    </issue>
+
+    <issue
+        id="AutoboxingStateCreation"
+        message="Prefer `mutableIntStateOf` instead of `mutableStateOf`"
+        errorLine1="    var remaining by remember(next?.linkId) { mutableStateOf(UP_NEXT_SECONDS) }"
+        errorLine2="                                              ~~~~~~~~~~~~~~">
+        <location
+            file="src/main/java/io/narl/protonstream/playback/PlayerScreen.kt"
+            line="707"
+            column="47"/>
+    </issue>
+
+    <issue
+        id="UseKtx"
+        message="Use the KTX extension function `SharedPreferences.edit` instead?"
+        errorLine1="        check(preferences.edit().putString(key, Base64.encodeToString(payload, Base64.NO_WRAP)).commit())"
+        errorLine2="              ~~~~~~~~~~~~~~~~~~">
+        <location
+            file="src/main/java/io/narl/protonstream/native/KeystoreSecretStore.kt"
+            line="41"
+            column="15"/>
+    </issue>
+
+    <issue
+        id="UseKtx"
+        message="Use the KTX extension function `SharedPreferences.edit` instead?"
+        errorLine1="        check(preferences.edit().remove(key).commit())"
+        errorLine2="              ~~~~~~~~~~~~~~~~~~">
+        <location
+            file="src/main/java/io/narl/protonstream/native/KeystoreSecretStore.kt"
+            line="64"
+            column="15"/>
+    </issue>
+
+    <issue
+        id="UseKtx"
+        message="Use the KTX extension function `SharedPreferences.edit` instead?"
+        errorLine1="        set(value) { preferences.edit().putBoolean(KEY_WIFI_ONLY, value).apply() }"
+        errorLine2="                     ~~~~~~~~~~~~~~~~~~">
+        <location
+            file="src/main/java/io/narl/protonstream/settings/SettingsStore.kt"
+            line="10"
+            column="22"/>
+    </issue>
+
+    <issue
+        id="UseKtx"
+        message="Use the KTX extension function `SharedPreferences.edit` instead?"
+        errorLine1="        set(value) { preferences.edit().putBoolean(KEY_BACKGROUND_AUDIO, value).apply() }"
+        errorLine2="                     ~~~~~~~~~~~~~~~~~~">
+        <location
+            file="src/main/java/io/narl/protonstream/settings/SettingsStore.kt"
+            line="14"
+            column="22"/>
+    </issue>
+
+    <issue
+        id="UseKtx"
+        message="Use the KTX extension function `SharedPreferences.edit` instead?"
+        errorLine1="        set(value) { preferences.edit().putBoolean(KEY_AUTO_SKIP, value).apply() }"
+        errorLine2="                     ~~~~~~~~~~~~~~~~~~">
+        <location
+            file="src/main/java/io/narl/protonstream/settings/SettingsStore.kt"
+            line="25"
+            column="22"/>
+    </issue>
+
+    <issue
+        id="UseKtx"
+        message="Use the KTX extension function `SharedPreferences.edit` instead?"
+        errorLine1="        set(value) { preferences.edit().putBoolean(KEY_AUTOPLAY, value).apply() }"
+        errorLine2="                     ~~~~~~~~~~~~~~~~~~">
+        <location
+            file="src/main/java/io/narl/protonstream/settings/SettingsStore.kt"
+            line="30"
+            column="22"/>
+    </issue>
+
+</issues>

android/app/proguard-instrumentation.pro

@@ -0,0 +1,98 @@
+# Keeps that exist so the instrumentation suite can run against the *release*
+# build. They are applied to the shipping APK, which is a real trade-off worth
+# stating plainly: the tested artifact is not byte-identical to an artifact
+# built without them.
+#
+# It is the better side of the trade. The alternative is to run instrumentation
+# against `debug` only, which leaves R8 — the step that has already broken this
+# app twice, in ways no debug run can reproduce — entirely uncovered. What is
+# kept here is a few kilobytes of framework plumbing containing no application
+# logic and revealing nothing about the app.
+#
+# Why these keeps are needed at all: the instrumentation APK is minified in a
+# separate R8 run that consumes the app's mapping file, and links against the
+# app's classes at runtime. That arrangement fails in two ways.
+#
+# 1. The mapping file carries renames but not R8's parameter-permutation
+#    optimisation, so a permuted method resolves to the wrong descriptor from
+#    the test APK.
+# 2. A class that only the test APK reaches is unreachable from the app's call
+#    graph, so R8 removes it from the app APK — and the test APK does not
+#    bundle it, because it is supposed to come from the app.
+
+# The Kotlin runtime is where both failures land, because androidx.test is
+# itself Kotlin and shares the app's copy of the stdlib. Keeping it wholesale
+# rather than class by class is deliberate: each individual keep only moves the
+# crash to the next facade the runner happens to touch, which is a list nobody
+# can enumerate ahead of time. Three were hit before this rule replaced them:
+#
+#   NoSuchMethodError: No static method f(Ljava/lang/Object;Ljava/lang/String;)V
+#     in class Lo6/k;                     (o6.k = kotlin.jvm.internal.Intrinsics,
+#                                          whose parameters R8 had permuted —
+#                                          every Kotlin class calls it on entry,
+#                                          so nothing ran at all)
+#   NoClassDefFoundError: Lkotlin/LazyKt;  (androidx.test.platform.io.TestDirCalculator)
+#
+# Cost is roughly a megabyte of dex against a ~100 MB APK that is almost
+# entirely native libraries.
+-keep class kotlin.** { *; }
+
+# `AndroidJUnitRunner.onCreate` traces its own startup. Nothing in the app
+# reaches androidx.tracing, so R8 dropped it and the runner could not start:
+#
+#   java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/tracing/Trace;
+#   at androidx.test.runner.AndroidJUnitRunner.onCreate(AndroidJUnitRunner.java:307)
+-keep class androidx.tracing.** { *; }
+
+# A third shape of the same problem, and the one worth understanding: the app
+# only ever touches WorkManager through its implementation, so R8 vertically
+# merged the abstract `androidx.work.WorkManager` into `WorkManagerImpl` and the
+# abstract type stopped existing. It is absent from mapping.txt entirely rather
+# than renamed. The download tests declare fields of the public types, so JUnit's
+# field scan could not even construct the test class:
+#
+#   java.lang.NoClassDefFoundError: Failed resolution of: Landroidx/work/WorkManager;
+#   at org.junit.runners.model.TestClass.getSortedDeclaredFields(TestClass.java:77)
+#
+# Kept package-wide because the same merge can happen to any of the public API
+# types the tests name (WorkInfo, Data, Constraints), and finding out one crash
+# at a time costs a four-minute device round trip each.
+-keep class androidx.work.** { *; }
+
+# Everything above is framework plumbing. The last group is app code, and it is
+# the one keep in this file that costs real fidelity: R8 no longer optimises
+# these classes in the shipping build, so the suite no longer proves R8 handles
+# them correctly. It is a narrow loss — the surfaces R8 has actually
+# broken here are the FFI ones, and those are kept for functional reasons in
+# proguard-rules.pro and stay under test.
+#
+# The trigger was `DownloadStateStore.clear()`. It is not dead code — AppViewModel
+# calls it — but it has exactly one call site, so R8 inlined it and dropped the
+# method. Only a caller that resolves it by name, which is to say a test, notices:
+#
+#   java.lang.NoSuchMethodError: No virtual method clear()V
+#   in class Lio/narl/protonstream/download/c;
+#
+# Package-wide rather than class-by-class: Kotlin's top-level functions live in
+# a synthesised `...Kt` facade that no source file names, so keeping the classes
+# a test imports still leaves it missing `DownloadCoordinatorKt`.
+-keep class io.narl.protonstream.download.** { *; }
+
+# Same inlining, one layer out: the `wifiOnly` setter behind the download
+# constraint.
+#   java.lang.NoSuchMethodError: No virtual method setWifiOnly(Z)V in class Li5/a;
+-keep class io.narl.protonstream.settings.SettingsStore { *; }
+
+# The live cases drive the player directly, so the same inlining applies to the
+# playback classes they name.
+-keep class io.narl.protonstream.playback.** { *; }
+
+# `runBlocking` — the live cases drive suspending bridge calls from a JUnit
+# thread. The app itself never blocks a thread on a coroutine, so R8 drops the
+# facade that holds it:
+#
+#   java.lang.NoClassDefFoundError: Failed resolution of: Lkotlinx/coroutines/BuildersKt;
+#
+# Kept narrowly rather than as `kotlinx.coroutines.**`: that library is large and
+# on the app's hot paths, and pinning all of it would cost real optimisation.
+-keep class kotlinx.coroutines.BuildersKt** { *; }

android/app/proguard-rules.pro

@@ -7,3 +7,19 @@
 -keepclasseswithmembernames class * {
     native <methods>;
 }
+
+# UniFFI records are Kotlin data classes whose generic signatures and
+# annotations survive into the runtime; stripping them changes how the bindings
+# lift and lower structured types.
+-keepattributes Signature,*Annotation*,InnerClasses,EnclosingMethod
+
+# JNA dispatches into callbacks reflectively by method name.
+-keepclassmembers class * implements com.sun.jna.Callback {
+    <methods>;
+}
+
+# The bridge calls back into these from Rust. Nothing in the Kotlin call graph
+# reaches their overrides, so R8 is free to rename or drop them.
+-keep class io.narl.protonstream.native.KeystoreSecretStore { *; }
+-keep class * implements uniffi.pstr_android.AndroidSecretStore { *; }
+-keep class * implements uniffi.pstr_android.DownloadObserver { *; }

android/app/proguard-test-rules.pro

@@ -0,0 +1,11 @@
+# Applied only to the instrumentation APK when androidTest runs against a
+# minified build (ANDROID_TEST_BUILD_TYPE=release). The tests exist to prove the
+# *app's* R8 configuration is right, so nothing here may relax the app's rules —
+# it only keeps the test harness itself intact.
+-dontobfuscate
+-keep class io.narl.protonstream.** { *; }
+-keep class androidx.test.** { *; }
+-dontwarn androidx.test.**
+-keepclasseswithmembers class * {
+    @org.junit.Test <methods>;
+}

android/app/src/androidTest/java/io/narl/protonstream/download/DownloadCoordinatorInstrumentedTest.kt

@@ -0,0 +1,129 @@
+package io.narl.protonstream.download
+
+import android.content.Context
+import androidx.test.core.app.ApplicationProvider
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.work.Configuration
+import androidx.work.NetworkType
+import androidx.work.WorkInfo
+import androidx.work.WorkManager
+import androidx.work.testing.SynchronousExecutor
+import androidx.work.testing.WorkManagerTestInitHelper
+import io.narl.protonstream.settings.SettingsStore
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * What actually reaches WorkManager. The unit tests cover the pure helpers; this
+ * covers the enqueue itself — the input data (which is persisted unencrypted, so
+ * it must carry no secret), the constraints, and the unique-work identity that
+ * pause and resume depend on.
+ */
+@RunWith(AndroidJUnit4::class)
+class DownloadCoordinatorInstrumentedTest {
+    private lateinit var context: Context
+    private lateinit var workManager: WorkManager
+
+    @Before
+    fun setUp() {
+        context = ApplicationProvider.getApplicationContext()
+        WorkManagerTestInitHelper.initializeTestWorkManager(
+            context,
+            Configuration.Builder().setExecutor(SynchronousExecutor()).build(),
+        )
+        workManager = WorkManager.getInstance(context)
+        workManager.cancelAllWork().result.get()
+        DownloadStateStore(context).clear()
+    }
+
+    private fun download(linkId: String = "link-1", shareId: String = "share-1") = RetainedDownload(
+        shareId = shareId,
+        volumeId = "volume-1",
+        linkId = linkId,
+        label = "S01E01.mkv",
+    )
+
+    private fun infoFor(download: RetainedDownload): WorkInfo? =
+        workManager.getWorkInfosForUniqueWork(
+            DownloadCoordinator.workName(download.shareId, download.linkId),
+        ).get().firstOrNull()
+
+    @Test
+    fun resumingEnqueuesUniqueWorkAndRetainsAQueuedRecord() {
+        val download = download()
+        DownloadCoordinator.resume(context, download)
+
+        assertNotNull(infoFor(download))
+        assertEquals(
+            RetainedDownload.STATUS_QUEUED,
+            DownloadStateStore(context).get("share-1", "link-1")?.status,
+        )
+    }
+
+    /**
+     * Tags are persisted in `androidx.work.workdb` unencrypted and are what the
+     * UI queries and what cancel-by-share matches on. Pinning the exact set is
+     * what makes an accidental addition — a fragment, a URL — visible in review.
+     */
+    @Test
+    fun theWorkCarriesExactlyTheExpectedTags() {
+        val download = download()
+        DownloadCoordinator.resume(context, download)
+
+        val tags = infoFor(download)?.tags.orEmpty()
+        assertTrue(DownloadCoordinator.TAG in tags)
+        assertTrue(DownloadCoordinator.shareTag("share-1") in tags)
+        assertTrue("${DownloadCoordinator.EPISODE_TAG}S01E01.mkv" in tags)
+        // The remaining tag is WorkManager's own worker class name.
+        assertEquals(4, tags.size)
+    }
+
+    @Test
+    fun theWifiOnlySettingReachesTheConstraint() {
+        // Documents B29: the constraint is read at enqueue time, so work already
+        // queued keeps whatever was set when it was queued. When B29 is fixed,
+        // this test grows a case for flipping the toggle after enqueue.
+        SettingsStore(context).wifiOnly = true
+        assertEquals(NetworkType.UNMETERED, requiredNetworkType(SettingsStore(context).wifiOnly))
+        SettingsStore(context).wifiOnly = false
+        assertEquals(NetworkType.CONNECTED, requiredNetworkType(SettingsStore(context).wifiOnly))
+    }
+
+    @Test
+    fun pauseCancelsTheWorkAndRecordsThePausedStatus() {
+        val download = download()
+        DownloadCoordinator.resume(context, download)
+        DownloadCoordinator.pause(context, download)
+
+        assertTrue(infoFor(download)?.state?.isFinished ?: false)
+        assertEquals(
+            RetainedDownload.STATUS_PAUSED,
+            DownloadStateStore(context).get("share-1", "link-1")?.status,
+        )
+    }
+
+    @Test
+    fun cancellingOneShareLeavesAnotherSharesWorkAlone() {
+        val first = download(linkId = "a", shareId = "share-1")
+        val second = download(linkId = "b", shareId = "share-2")
+        DownloadCoordinator.resume(context, first)
+        DownloadCoordinator.resume(context, second)
+
+        workManager.cancelAllWorkByTag(DownloadCoordinator.shareTag("share-1")).result.get()
+
+        assertTrue(infoFor(first)?.state?.isFinished ?: false)
+        assertEquals(WorkInfo.State.ENQUEUED, infoFor(second)?.state)
+    }
+
+    @Test
+    fun twoEpisodesOfOneShareEnqueueSeparately() {
+        DownloadCoordinator.resume(context, download(linkId = "a"))
+        DownloadCoordinator.resume(context, download(linkId = "b"))
+
+        assertEquals(2, workManager.getWorkInfosByTag(DownloadCoordinator.TAG).get().size)
+    }
+}

android/app/src/androidTest/java/io/narl/protonstream/live/LiveShareTest.kt

@@ -0,0 +1,274 @@
+package io.narl.protonstream.live
+
+import android.graphics.SurfaceTexture
+import android.view.Surface
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import io.narl.protonstream.playback.NativeMpvHost
+import java.io.File
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicLong
+import kotlinx.coroutines.runBlocking
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertTrue
+import org.junit.Assume.assumeTrue
+import org.junit.BeforeClass
+import org.junit.Test
+import org.junit.runner.RunWith
+import uniffi.pstr_android.AndroidEngine
+import uniffi.pstr_android.AndroidPaths
+import uniffi.pstr_android.AndroidSecretStore
+import uniffi.pstr_android.DownloadObserver
+import uniffi.pstr_android.EpisodeRecord
+
+/**
+ * The cases `docs/ANDROID.md` requires that cannot be answered without a real
+ * share: that a link resolves into a playable catalog, that libmpv actually
+ * decodes the decrypted stream, that a cancelled download leaves a resumable
+ * `.part`, and that a resume position survives a restart.
+ *
+ * The link is an instrumentation argument rather than a constant or a file, so
+ * the secret never enters the repository:
+ *
+ * ```
+ * -Pandroid.testInstrumentationRunnerArguments.pstr.shareUrl=...
+ * ```
+ *
+ * Without it every test here is skipped by assumption, and
+ * `scripts/android-acceptance.sh` reports the matrix as incomplete.
+ *
+ * Read-only against the share by construction: nothing here uploads, renames or
+ * deletes anything remote. It writes only to this test's own temporary
+ * directories.
+ */
+@RunWith(AndroidJUnit4::class)
+class LiveShareTest {
+    @Test
+    fun theShareResolvesIntoAPlayableCatalog() {
+        val episodes = episodes()
+        assertTrue("the crawl found no playable file in the share", episodes.isNotEmpty())
+        // A file with no size cannot be streamed: the block layer needs the
+        // length to place block boundaries at all.
+        val sized = episodes.filter { (it.size ?: 0uL) > 0uL }
+        assertTrue("no episode in the share reported a size", sized.isNotEmpty())
+    }
+
+    @Test
+    fun openingAnEpisodeYieldsASeekableRevision() {
+        val episode = playable()
+        val stream = runBlocking {
+            engine.openStream(episode.shareId, episode.volumeId, episode.linkId)
+        }
+        try {
+            assertTrue("the opened revision has no length", stream.size() > 0uL)
+            // Without a revision id the block cache cannot tell one revision of
+            // a file from another, and a stale block would be served as fresh.
+            assertTrue("the opened revision has no id", stream.revisionId().isNotBlank())
+        } finally {
+            runBlocking { engine.releaseStream(episode.shareId, episode.volumeId, episode.linkId) }
+        }
+    }
+
+    /**
+     * The whole pipeline in one assertion: Proton block storage, decryption,
+     * the Rust stream C ABI, the JNI adapter and libmpv's demuxer. If the
+     * position advances, real decrypted bytes reached the decoder.
+     */
+    @Test
+    fun libmpvDecodesTheDecryptedStream() {
+        val episode = playable()
+        val texture = SurfaceTexture(0).apply { setDefaultBufferSize(1280, 720) }
+        val surface = Surface(texture)
+        val host = NativeMpvHost()
+        val key = "${episode.shareId}:${episode.linkId}"
+        try {
+            host.attachSurface(surface)
+            val stream = runBlocking {
+                engine.openStream(episode.shareId, episode.volumeId, episode.linkId)
+            }
+            runBlocking { host.play(key, stream.nativeHandle(), stream.size()) }
+            host.setMuted(true)
+            host.setPaused(false)
+
+            val playing = waitFor(PLAYBACK_TIMEOUT_MS) { host.state.value.position > 0.0 }
+            assertTrue(
+                "libmpv never advanced past zero: ${host.state.value}",
+                playing,
+            )
+            // One host serves every episode in turn, so a reading that does not
+            // name this one would resume the wrong file.
+            assertEquals(key, host.state.value.media)
+            assertTrue("libmpv reported no duration", host.state.value.duration > 0.0)
+        } finally {
+            host.stop()
+            host.detachSurface()
+            host.close()
+            surface.release()
+            texture.release()
+            runBlocking { engine.releaseStream(episode.shareId, episode.volumeId, episode.linkId) }
+        }
+    }
+
+    /**
+     * Cancellation is polled between whole Proton blocks precisely so the bytes
+     * already written stay usable. This checks the retained `.part` is counted
+     * as partial rather than as a finished file, and that resuming continues
+     * from it instead of starting over.
+     */
+    @Test
+    fun aCancelledDownloadLeavesAResumablePartFile() {
+        val episode = playable()
+        val firstRun = CancelAfter(bytes = RESUME_THRESHOLD_BYTES)
+        runCatching {
+            runBlocking {
+                engine.downloadEpisode(episode.shareId, episode.volumeId, episode.linkId, firstRun)
+            }
+        }
+        assumeTrue(
+            "the episode finished before cancellation could be observed; it is too small for this case",
+            !firstRun.completed,
+        )
+        assertTrue("the download reported no progress at all", firstRun.observed > 0L)
+
+        val retained = engine.storageUsage()
+        assertTrue("a cancelled download retained no bytes", retained.partialBytes > 0uL)
+        assertEquals("a cancelled download counted as a finished file", 0uL, retained.offlineCount)
+
+        // Resuming must pick up where the .part ended rather than at zero.
+        val secondRun = CancelAfter(bytes = retained.partialBytes.toLong() + RESUME_THRESHOLD_BYTES)
+        runCatching {
+            runBlocking {
+                engine.downloadEpisode(episode.shareId, episode.volumeId, episode.linkId, secondRun)
+            }
+        }
+        assertTrue(
+            "resuming restarted from zero: first reading was ${secondRun.firstReading}, " +
+                "but ${retained.partialBytes} bytes were already retained",
+            secondRun.firstReading >= retained.partialBytes.toLong(),
+        )
+
+        runBlocking { engine.removeOfflineEpisode(episode.shareId, episode.linkId) }
+        assertEquals(
+            "removing the episode left partial bytes behind",
+            0uL,
+            engine.storageUsage().partialBytes,
+        )
+    }
+
+    /** What the viewer sees as "continue watching" after the app is killed. */
+    @Test
+    fun aResumePositionSurvivesReopeningTheCatalog() {
+        val episode = playable()
+        engine.saveWatchState(episode.shareId, episode.linkId, RESUME_POSITION, null, false)
+
+        val reopened = AndroidEngine(paths, secrets)
+        val state = reopened.watchState(episode.shareId, episode.linkId)
+        assertNotNull("the resume position did not survive a reopen", state)
+        assertEquals(RESUME_POSITION, state!!.positionSecs, 0.001)
+        assertEquals(false, state.watched)
+
+        // The catalog view is what the UI reads, so it has to agree.
+        val listed = reopened.library(null)
+            .flatMap { it.seasons }
+            .flatMap { it.episodes }
+            .first { it.linkId == episode.linkId }
+        assertEquals(RESUME_POSITION, listed.resumeAt ?: -1.0, 0.001)
+    }
+
+    /** Cancels once the download has written enough to prove a resume. */
+    private class CancelAfter(private val bytes: Long) : DownloadObserver {
+        private val cancelled = AtomicBoolean(false)
+        private val progress = AtomicLong(0)
+        private val first = AtomicLong(-1)
+
+        val observed: Long get() = progress.get()
+        val firstReading: Long get() = first.get()
+        val completed: Boolean get() = !cancelled.get()
+
+        override fun onProgress(downloaded: ULong, total: ULong) {
+            first.compareAndSet(-1, downloaded.toLong())
+            progress.set(downloaded.toLong())
+            if (downloaded.toLong() >= bytes) cancelled.set(true)
+        }
+
+        override fun isCancelled(): Boolean = cancelled.get()
+    }
+
+    private fun episodes(): List<EpisodeRecord> =
+        engine.library(null).flatMap { it.seasons }.flatMap { it.episodes }
+
+    private fun playable(): EpisodeRecord =
+        episodes().firstOrNull { (it.size ?: 0uL) > 0uL }
+            ?: throw AssertionError("the share has no sized file to play")
+
+    private fun waitFor(timeoutMs: Long, condition: () -> Boolean): Boolean {
+        val deadline = System.currentTimeMillis() + timeoutMs
+        while (System.currentTimeMillis() < deadline) {
+            if (condition()) return true
+            Thread.sleep(200)
+        }
+        return false
+    }
+
+    /** Stands in for Keystore, so a bridge failure cannot be blamed on crypto. */
+    private class MemorySecretStore : AndroidSecretStore {
+        private val entries = ConcurrentHashMap<String, String>()
+
+        override fun set(key: String, value: String) {
+            entries[key] = value
+        }
+
+        override fun get(key: String): String? = entries[key]
+
+        override fun delete(key: String) {
+            entries.remove(key)
+        }
+    }
+
+    companion object {
+        private const val SHARE_URL_ARGUMENT = "pstr.shareUrl"
+        private const val SHARE_PASSWORD_ARGUMENT = "pstr.sharePassword"
+
+        /** Long enough for a cold connection, a crawl and a first block read. */
+        private const val PLAYBACK_TIMEOUT_MS = 60_000L
+
+        /** Enough written bytes to prove a resume, small enough to stay quick. */
+        private const val RESUME_THRESHOLD_BYTES = 4L * 1024 * 1024
+
+        private const val RESUME_POSITION = 137.5
+
+        private lateinit var paths: AndroidPaths
+        private lateinit var secrets: AndroidSecretStore
+        private lateinit var engine: AndroidEngine
+
+        @BeforeClass
+        @JvmStatic
+        fun openTheShare() {
+            System.loadLibrary("pstr_android")
+            val arguments = InstrumentationRegistry.getArguments()
+            val url = arguments.getString(SHARE_URL_ARGUMENT)
+            assumeTrue(
+                "set -Pandroid.testInstrumentationRunnerArguments.$SHARE_URL_ARGUMENT to run the live cases",
+                !url.isNullOrBlank(),
+            )
+            val password = arguments.getString(SHARE_PASSWORD_ARGUMENT)?.takeIf { it.isNotBlank() }
+
+            val root = File.createTempFile("pstr-live", "").let {
+                it.delete()
+                it.mkdirs()
+                it
+            }
+            paths = AndroidPaths(
+                File(root, "config").absolutePath,
+                File(root, "data").absolutePath,
+                File(root, "cache").absolutePath,
+            )
+            secrets = MemorySecretStore()
+            engine = AndroidEngine(paths, secrets)
+            engine.addShare("acceptance", url!!, password)
+            runBlocking { engine.crawl(null) }
+        }
+    }
+}

android/app/src/androidTest/java/io/narl/protonstream/native/KeystoreSecretStoreTest.kt

@@ -0,0 +1,155 @@
+package io.narl.protonstream.native
+
+import android.content.Context
+import android.util.Base64
+import androidx.test.core.app.ApplicationProvider
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import java.security.KeyStore
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertThrows
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import uniffi.pstr_android.BridgeException
+
+/**
+ * Runs on a device because Android Keystore has no host implementation — which
+ * is why nothing pinned this before. The share fragment and any custom link
+ * password are the only user secrets the app holds, and losing the key makes
+ * every share unopenable, so the failure modes matter as much as the happy path.
+ */
+@RunWith(AndroidJUnit4::class)
+class KeystoreSecretStoreTest {
+    private lateinit var context: Context
+    private lateinit var store: KeystoreSecretStore
+
+    @Before
+    fun setUp() {
+        context = ApplicationProvider.getApplicationContext()
+        clearPreferences()
+        store = KeystoreSecretStore(context)
+    }
+
+    @After
+    fun tearDown() {
+        clearPreferences()
+    }
+
+    @Test
+    fun aSecretSurvivesARoundTrip() {
+        store.set("share-1", "correct horse battery staple")
+        assertEquals("correct horse battery staple", store.get("share-1"))
+    }
+
+    @Test
+    fun anAbsentSecretIsNullRatherThanEmpty() {
+        assertNull(store.get("never-written"))
+    }
+
+    @Test
+    fun deleteRemovesTheSecret() {
+        store.set("share-1", "value")
+        store.delete("share-1")
+        assertNull(store.get("share-1"))
+    }
+
+    @Test
+    fun aUnicodeSecretIsNotMangled() {
+        val value = "パスワード・🎬・ü"
+        store.set("share-1", value)
+        assertEquals(value, store.get("share-1"))
+    }
+
+    /**
+     * GCM is catastrophic under IV reuse: two secrets encrypted with the same
+     * key and IV leak the XOR of their plaintexts. `Cipher.init(ENCRYPT_MODE)`
+     * is what generates a fresh one, so this pins that the code never pins it.
+     */
+    @Test
+    fun everyWriteUsesAFreshInitialisationVector() {
+        store.set("share-1", "same plaintext")
+        val first = rawPayload("share-1")
+        store.set("share-1", "same plaintext")
+        val second = rawPayload("share-1")
+
+        val firstIv = first.copyOfRange(0, IV_SIZE)
+        val secondIv = second.copyOfRange(0, IV_SIZE)
+        assertNotEquals(Base64.encodeToString(firstIv, Base64.NO_WRAP), Base64.encodeToString(secondIv, Base64.NO_WRAP))
+    }
+
+    @Test
+    fun theStoredFormIsNotThePlaintext() {
+        store.set("share-1", "correct horse battery staple")
+        val stored = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+            .getString("share-1", null)
+        assertTrue(stored != null && !stored.contains("correct horse"))
+    }
+
+    /**
+     * A tampered payload must not decrypt, and must fail as a [BridgeException].
+     * An `AEADBadTagException` crossing the FFI has no mapping on the Rust side,
+     * and an unmapped callback exception panics the calling thread (B18).
+     */
+    @Test
+    fun aTamperedPayloadFailsToDecrypt() {
+        store.set("share-1", "value")
+        val payload = rawPayload("share-1")
+        payload[payload.size - 1] = (payload[payload.size - 1].toInt() xor 0x01).toByte()
+        writeRawPayload("share-1", payload)
+
+        assertThrows(BridgeException::class.java) { store.get("share-1") }
+    }
+
+    @Test
+    fun aTruncatedPayloadIsRejectedBeforeDecryption() {
+        store.set("share-1", "value")
+        writeRawPayload("share-1", rawPayload("share-1").copyOfRange(0, IV_SIZE))
+
+        assertThrows(BridgeException::class.java) { store.get("share-1") }
+    }
+
+    /**
+     * The device-side half of B18: this is what a lockscreen change or a device
+     * restore does to the key. It must fail the read rather than the process,
+     * and the store must still accept a re-entered secret afterwards — which is
+     * what the shares screen's "Re-enter link" depends on.
+     */
+    @Test
+    fun aLostKeyFailsTheReadRatherThanTheProcess() {
+        store.set("share-1", "value")
+        KeyStore.getInstance("AndroidKeyStore").apply { load(null) }.deleteEntry(KEY_ALIAS)
+
+        assertThrows(BridgeException::class.java) { store.get("share-1") }
+
+        // The store must still be usable for a re-entered secret.
+        store.set("share-1", "re-entered")
+        assertEquals("re-entered", store.get("share-1"))
+    }
+
+    private fun rawPayload(key: String): ByteArray {
+        val encoded = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+            .getString(key, null) ?: error("no payload for $key")
+        return Base64.decode(encoded, Base64.NO_WRAP)
+    }
+
+    private fun writeRawPayload(key: String, payload: ByteArray) {
+        context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+            .edit()
+            .putString(key, Base64.encodeToString(payload, Base64.NO_WRAP))
+            .commit()
+    }
+
+    private fun clearPreferences() {
+        context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE).edit().clear().commit()
+    }
+
+    private companion object {
+        const val PREFERENCES = "proton_stream_secrets"
+        const val KEY_ALIAS = "proton-stream-share-secrets-v1"
+        const val IV_SIZE = 12
+    }
+}

android/app/src/androidTest/java/io/narl/protonstream/native/UniFfiBoundaryTest.kt

@@ -0,0 +1,117 @@
+package io.narl.protonstream.native
+
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import java.io.File
+import java.util.concurrent.ConcurrentHashMap
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.BeforeClass
+import org.junit.Test
+import org.junit.runner.RunWith
+import uniffi.pstr_android.AndroidEngine
+import uniffi.pstr_android.AndroidPaths
+import uniffi.pstr_android.AndroidSecretStore
+import uniffi.pstr_android.chapterPlan
+import uniffi.pstr_android.skipOffer
+
+/**
+ * The first thing that crosses the UniFFI boundary on a real device. It is
+ * deliberately offline: it proves the ABI, the generated bindings, the callback
+ * interface and the SQLite open all work, without needing a share.
+ *
+ * If this fails and the Rust workspace tests pass, the fault is in packaging —
+ * a missing ABI in `jniLibs`, a stale binding, or an R8 rule (run it with
+ * `ANDROID_TEST_BUILD_TYPE=release` to check the shipped configuration).
+ */
+@RunWith(AndroidJUnit4::class)
+class UniFfiBoundaryTest {
+    /** Stands in for Keystore so a bridge failure cannot be blamed on crypto. */
+    private class MemorySecretStore : AndroidSecretStore {
+        val entries = ConcurrentHashMap<String, String>()
+        var reads = 0
+            private set
+
+        override fun set(key: String, value: String) {
+            entries[key] = value
+        }
+
+        override fun get(key: String): String? {
+            reads += 1
+            return entries[key]
+        }
+
+        override fun delete(key: String) {
+            entries.remove(key)
+        }
+    }
+
+    private fun engine(secrets: AndroidSecretStore = MemorySecretStore()): AndroidEngine {
+        val root = File.createTempFile("pstr-bridge", "").let {
+            it.delete()
+            it.mkdirs()
+            it
+        }
+        return AndroidEngine(
+            AndroidPaths(
+                File(root, "config").absolutePath,
+                File(root, "data").absolutePath,
+                File(root, "cache").absolutePath,
+            ),
+            secrets,
+        )
+    }
+
+    @Test
+    fun theEngineOpensAgainstEmptyDirectories() {
+        val engine = engine()
+        assertTrue(engine.shares().isEmpty())
+        assertTrue(engine.library(null).isEmpty())
+    }
+
+    @Test
+    fun storageUsageReportsZeroOnAFreshInstall() {
+        val usage = engine().storageUsage()
+        assertNotNull(usage)
+        assertEquals(0UL, usage.offlineBytes)
+        assertEquals(0UL, usage.partialBytes)
+        assertEquals(0UL, usage.offlineCount)
+    }
+
+    @Test
+    fun metadataSettingsAreReadableAndDefaultToDisabled() {
+        // Enrichment is opt-in; a default of enabled would send titles to a
+        // third party before the viewer has agreed to it.
+        assertEquals(false, engine().metadataSettings().enabled)
+    }
+
+    @Test
+    fun aSecondEngineReopensTheSameCatalog() {
+        val secrets = MemorySecretStore()
+        engine(secrets).shares()
+        // Reopening is the process-restart path; a schema or lock fault shows up
+        // here rather than on a user's device.
+        assertTrue(engine(secrets).shares().isEmpty())
+    }
+
+    /**
+     * Chapter classification is shared Rust that desktop already pins
+     * (`docs/BUGS.md` B12). This runs the same code through the bindings, so a
+     * lowering fault in the record types cannot pass unnoticed.
+     */
+    @Test
+    fun chapterPlanningCrossesTheBoundaryIntact() {
+        val plan = chapterPlan(emptyList(), 1560.0)
+        assertNotNull(plan)
+        assertNull(skipOffer(plan, 12.0))
+    }
+
+    companion object {
+        @BeforeClass
+        @JvmStatic
+        fun loadLibrary() {
+            System.loadLibrary("pstr_android")
+        }
+    }
+}

android/app/src/main/AndroidManifest.xml

@@ -29,7 +29,7 @@
 
         <activity
             android:name=".MainActivity"
-            android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation"
+            android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation|uiMode|density|fontScale|locale|layoutDirection|keyboardHidden"
             android:exported="true"
             android:launchMode="singleTask"
             android:supportsPictureInPicture="true"

android/app/src/main/cpp/CMakeLists.txt

@@ -12,6 +12,12 @@ add_library(pstr_mpv SHARED pstr_mpv.cpp)
 add_library(mpv SHARED IMPORTED)
 set_target_properties(mpv PROPERTIES
     IMPORTED_LOCATION "${PSTR_MPV_ROOT}/jniLibs/${ANDROID_ABI}/libmpv.so")
+# libmpv links FFmpeg dynamically and does not re-export it, so registering the
+# JavaVM that MediaCodec needs means linking libavcodec ourselves. It is already
+# packaged in the same ABI directory as part of libmpv's dependency closure.
+add_library(avcodec SHARED IMPORTED)
+set_target_properties(avcodec PROPERTIES
+    IMPORTED_LOCATION "${PSTR_MPV_ROOT}/jniLibs/${ANDROID_ABI}/libavcodec.so")
 
 target_compile_features(pstr_mpv PRIVATE cxx_std_20)
 target_compile_options(pstr_mpv PRIVATE -Wall -Wextra -Werror)
@@ -20,4 +26,4 @@ target_include_directories(pstr_mpv PRIVATE "${PSTR_MPV_ROOT}/include")
 # packaged into the same ABI directory in the APK.
 target_link_directories(pstr_mpv PRIVATE "${PSTR_RUST_JNI_ROOT}/${ANDROID_ABI}")
 target_link_options(pstr_mpv PRIVATE "-Wl,-l:libpstr_android.so")
-target_link_libraries(pstr_mpv PRIVATE mpv android EGL log)
+target_link_libraries(pstr_mpv PRIVATE mpv avcodec android EGL log)

android/app/src/main/cpp/pstr_mpv.cpp

@@ -1,6 +1,7 @@
 #include "pstr_mpv.h"
 
 #include <EGL/egl.h>
+#include <android/log.h>
 #include <android/native_window.h>
 #include <android/native_window_jni.h>
 #include <jni.h>
@@ -8,6 +9,10 @@
 #include <mpv/render_gl.h>
 #include <mpv/stream_cb.h>
 
+extern "C" {
+#include <libavcodec/jni.h>
+}
+
 #include <atomic>
 #include <algorithm>
 #include <charconv>
@@ -86,16 +91,32 @@ int64_t stream_size(void *opaque) noexcept {
     });
 }
 
+/// mpv wants its request slot back — a seek, or a teardown.
+///
+/// The flag alone only stops the *next* read; the one already parked in a 4 MiB
+/// block fetch has to be interrupted in Rust, or `mpv_terminate_destroy` waits
+/// out the whole fetch while joining the demuxer thread.
 void stream_cancel(void *opaque) noexcept {
     c_boundary([=] {
         if (auto *stream = static_cast<StreamCookie *>(opaque)) {
             stream->cancelled.store(true, std::memory_order_relaxed);
+            pstr_android_stream_cancel(stream->handle);
         }
     });
 }
 
+/// Releases the Rust stream behind the file mpv has finished with.
+///
+/// Ownership sits here rather than in Kotlin because this is the one moment
+/// that is *defined* to be after mpv's last read: `loadfile` is asynchronous, so
+/// a Kotlin-side release issued when the next load returns can land while the
+/// outgoing demuxer is still reading — and, if the release names the handle the
+/// registry has already swapped, takes the incoming episode's stream with it.
 void stream_close(void *opaque) noexcept {
-    c_boundary([=] { delete static_cast<StreamCookie *>(opaque); });
+    c_boundary([=] {
+        std::unique_ptr<StreamCookie> cookie(static_cast<StreamCookie *>(opaque));
+        if (cookie) pstr_android_stream_release(cookie->handle);
+    });
 }
 
 int stream_open(void *, char *uri, mpv_stream_cb_info *info) noexcept {
@@ -130,6 +151,29 @@ void *resolve_gl(void *, const char *name) noexcept {
     });
 }
 
+/// Why the open file ended, mirroring `pstr_player::EndReason` so that the two
+/// clients agree on what "finished" means. Only [Eof] is an episode the viewer
+/// watched to the end; the rest are a stop, a shutdown or a failure, and none of
+/// them may mark anything watched or advance to the next episode.
+enum class EndReason : int {
+    None = 0,
+    Eof = 1,
+    Stopped = 2,
+    Quit = 3,
+    Failed = 4,
+    Other = 5,
+};
+
+EndReason end_reason_of(int reason) {
+    switch (reason) {
+        case MPV_END_FILE_REASON_EOF: return EndReason::Eof;
+        case MPV_END_FILE_REASON_STOP: return EndReason::Stopped;
+        case MPV_END_FILE_REASON_QUIT: return EndReason::Quit;
+        case MPV_END_FILE_REASON_ERROR: return EndReason::Failed;
+        default: return EndReason::Other;
+    }
+}
+
 struct PlaybackState {
     double position = 0.0;
     double duration = 0.0;
@@ -137,6 +181,30 @@ struct PlaybackState {
     bool paused = true;
     bool muted = false;
     bool ended = false;
+    EndReason end_reason = EndReason::None;
+    /// mpv has run out of buffered data and stopped to refill. Distinct from
+    /// [paused], which is the viewer's doing: a frozen picture that nothing
+    /// explains is indistinguishable from a hung app.
+    bool buffering = false;
+    /// How full the demuxer cache is while [buffering], 0–100.
+    double cache_percent = 0.0;
+    /// Between a seek being issued and playback actually resuming. The seek bar
+    /// has moved but the picture has not.
+    bool seeking = false;
+    /// True between `loadfile` being issued and mpv acknowledging it with
+    /// `START_FILE`. Everything mpv reports in that window still describes the
+    /// *outgoing* file — including the `END_FILE(STOP)` that stopping it emits —
+    /// and must not be attributed to the file being loaded.
+    bool loading = false;
+    /// The picture's display size, once mpv has decoded enough to know it.
+    /// Zero until then, and the aspect Picture-in-Picture is given.
+    double video_width = 0.0;
+    double video_height = 0.0;
+    /// Which loaded file this state describes. Bumped by every load, so a
+    /// reader can tell "episode two, second zero" from a leftover reading of
+    /// episode one — which is the difference between resuming an episode where
+    /// the viewer left it and resuming it where the *previous* one ended.
+    int64_t generation = 0;
 };
 
 class Player {
@@ -148,7 +216,15 @@ class Player {
         option("vo", "libmpv");
         option("force-window", "no");
         option("video-timing-offset", "0");
-        option("hwdec", "auto-safe");
+        // `-copy-safe`, not `-safe`. The direct MediaCodec decoders render into
+        // an `ANativeWindow` the decoder is handed at init, and this player has
+        // none to give: the picture goes through `vo_libmpv` and an EGL pbuffer,
+        // and the SurfaceView — when there is one at all — attaches later than
+        // the load. `auto-safe` picks them anyway and every file opens with
+        // `hevc_mediacodec: Both surface and native_window are NULL` before
+        // falling back. The copy variants decode in hardware and hand back
+        // ordinary frames, which is what this render path can actually use.
+        option("hwdec", "auto-copy-safe");
         option("cache", "yes");
         option("cache-secs", "30");
         option("demuxer-readahead-secs", "30");
@@ -165,6 +241,13 @@ class Player {
         observe("pause", 3, MPV_FORMAT_FLAG);
         observe("volume", 4, MPV_FORMAT_DOUBLE);
         observe("mute", 5, MPV_FORMAT_FLAG);
+        observe("video-params/dw", 6, MPV_FORMAT_INT64);
+        observe("video-params/dh", 7, MPV_FORMAT_INT64);
+        observe("paused-for-cache", 8, MPV_FORMAT_FLAG);
+        observe("cache-buffering-state", 9, MPV_FORMAT_INT64);
+        // Errors mpv reports about the file itself, rather than about the
+        // request that opened it. Without these a failed demux is silent.
+        mpv_request_log_messages(mpv_, "error");
         events_ = std::thread([this] { event_loop(); });
         renderer_ = std::thread([this] { render_loop(); });
     }
@@ -213,23 +296,60 @@ class Player {
     bool load(uint64_t handle, double start, const std::string &audio,
               const std::string &subtitle, bool subtitles) {
         if (!mpv_) return false;
-        {
-            std::unique_lock lock(render_mutex_);
-            if (!render_cv_.wait_for(lock, std::chrono::seconds(5), [this] { return render_ != nullptr || !running_.load(); })) return false;
-        }
+        // No wait for a render context. It is created with the render thread and
+        // needs no window, and a load that cannot get one plays audio anyway —
+        // waiting for a surface here is what made background playback fail after
+        // a five-second stall.
         if (!audio.empty()) set_string("alang", audio);
         if (!subtitle.empty()) set_string("slang", subtitle);
         set_string("sid", subtitles ? "auto" : "no");
         pending_start_.store(std::max(0.0, start));
+        // Retire the outgoing file's position, duration and end flag *before*
+        // the new one loads. mpv only republishes them once it has demuxed
+        // enough of the stream, and until then every reader would otherwise see
+        // the last episode's clock under the new episode's name.
+        {
+            std::lock_guard lock(state_mutex_);
+            const double volume = state_.volume;
+            const bool muted = state_.muted;
+            // `pause` is a property of the core, not of the file: mpv carries it
+            // across `loadfile` unchanged and therefore never re-publishes it.
+            // Resetting it to the struct's default would leave every reader
+            // believing a playing file is paused for as long as it is open, and
+            // every "play" they then send is a no-op against a core that never
+            // paused — which is a play/pause button that does nothing.
+            const bool paused = state_.paused;
+            const int64_t generation = state_.generation + 1;
+            state_ = PlaybackState{};
+            state_.volume = volume;
+            state_.muted = muted;
+            state_.paused = paused;
+            state_.generation = generation;
+            state_.loading = true;
+            error_.clear();
+        }
         const std::string url = "pstr://" + std::to_string(handle);
         const char *command[] = {"loadfile", url.c_str(), nullptr};
-        if (mpv_command(mpv_, command) < 0) return false;
+        if (mpv_command(mpv_, command) < 0) {
+            // Nothing was issued, so no START_FILE will arrive to clear this.
+            std::lock_guard lock(state_mutex_);
+            state_.loading = false;
+            return false;
+        }
         return true;
     }
 
-    void pause(bool value) { set_flag("pause", value); }
+    /// Written through rather than left to the observer: the transport is drawn
+    /// from this state, and a tap that only shows its effect on mpv's next
+    /// property event reads as a button that missed.
+    void pause(bool value) {
+        set_flag("pause", value);
+        std::lock_guard lock(state_mutex_);
+        state_.paused = value;
+    }
     void seek(double seconds) { set_double("time-pos", std::max(0.0, seconds)); }
     void volume(double value) { set_double("volume", std::clamp(value, 0.0, 100.0)); }
+    void speed(double value) { set_double("speed", std::clamp(value, 0.25, 4.0)); }
     void mute(bool value) { set_flag("mute", value); }
     void select_track(bool audio, int64_t id) {
         const char *property = audio ? "aid" : "sid";
@@ -246,6 +366,12 @@ class Player {
         return state_;
     }
 
+    /// The pending error, if any, consumed by reading it.
+    std::string take_error() {
+        std::lock_guard lock(state_mutex_);
+        return std::exchange(error_, std::string());
+    }
+
     std::string tracks_json() const {
         if (!mpv_) return "[]";
         int64_t count = 0;
@@ -274,22 +400,115 @@ class Player {
         return json + ']';
     }
 
+    /// The file's chapters, read one sub-property at a time like the tracks.
+    /// What they *mean* is decided in Rust (`pstr_core::chapters`), so the
+    /// desktop and this client offer the same skips.
+    std::string chapters_json() const {
+        if (!mpv_) return "[]";
+        int64_t count = 0;
+        if (mpv_get_property(mpv_, "chapter-list/count", MPV_FORMAT_INT64, &count) < 0) return "[]";
+        std::string json = "[";
+        for (int64_t i = 0; i < count; ++i) {
+            const std::string base = "chapter-list/" + std::to_string(i) + "/";
+            char *title_raw = nullptr;
+            double start = 0.0;
+            mpv_get_property(mpv_, (base + "title").c_str(), MPV_FORMAT_STRING, &title_raw);
+            MpvString title(title_raw);
+            mpv_get_property(mpv_, (base + "time").c_str(), MPV_FORMAT_DOUBLE, &start);
+            if (i) json += ',';
+            json += "{\"index\":" + std::to_string(i) + ",\"title\":\"" + escape(title.get()) +
+                    "\",\"start\":" + std::to_string(start) + '}';
+        }
+        return json + ']';
+    }
+
   private:
     struct MpvFree {
         void operator()(char *value) const noexcept { if (value) mpv_free(value); }
     };
     using MpvString = std::unique_ptr<char, MpvFree>;
 
+    /// JSON-escape `text`, and re-encode it as Modified UTF-8.
+    ///
+    /// The result of this ends up in `NewStringUTF`, which does not take UTF-8:
+    /// it takes Modified UTF-8, where a character outside the basic plane is a
+    /// surrogate *pair* of three-byte sequences rather than one four-byte
+    /// sequence. Handing it real UTF-8 renders an emoji in a track title as
+    /// mojibake, and aborts the process under CheckJNI.
+    ///
+    /// Anything that is not well-formed UTF-8 is dropped rather than passed
+    /// through, for the same reason: a truncated sequence is what CheckJNI
+    /// rejects, and a track title is not worth a crash.
     static std::string escape(const char *text) {
         std::string out;
         if (!text) return out;
-        for (const unsigned char c : std::string_view(text)) {
-            if (c == '"' || c == '\\') out += '\\';
-            if (c >= 0x20) out += static_cast<char>(c);
+        const std::string_view input(text);
+        for (size_t i = 0; i < input.size();) {
+            const auto lead = static_cast<unsigned char>(input[i]);
+            size_t length = 0;
+            uint32_t code = 0;
+            if (lead < 0x80) {
+                length = 1;
+                code = lead;
+            } else if ((lead & 0xE0) == 0xC0) {
+                length = 2;
+                code = lead & 0x1Fu;
+            } else if ((lead & 0xF0) == 0xE0) {
+                length = 3;
+                code = lead & 0x0Fu;
+            } else if ((lead & 0xF8) == 0xF0) {
+                length = 4;
+                code = lead & 0x07u;
+            } else {
+                ++i; // A stray continuation or invalid lead byte.
+                continue;
+            }
+            if (i + length > input.size()) break;
+            bool valid = true;
+            for (size_t k = 1; k < length; ++k) {
+                const auto next = static_cast<unsigned char>(input[i + k]);
+                if ((next & 0xC0) != 0x80) {
+                    valid = false;
+                    break;
+                }
+                code = (code << 6) | (next & 0x3Fu);
+            }
+            if (!valid) {
+                ++i;
+                continue;
+            }
+            i += length;
+
+            if (code < 0x20) continue; // Control characters, including NUL.
+            if (code == '"' || code == '\\') {
+                out += '\\';
+                out += static_cast<char>(code);
+                continue;
+            }
+            if (code < 0x80) {
+                out += static_cast<char>(code);
+            } else if (code < 0x800) {
+                out += static_cast<char>(0xC0 | (code >> 6));
+                out += static_cast<char>(0x80 | (code & 0x3F));
+            } else if (code < 0x10000) {
+                append_three(out, code);
+            } else {
+                // The surrogate pair Modified UTF-8 wants, each half written as
+                // its own three-byte sequence.
+                const uint32_t rest = code - 0x10000;
+                append_three(out, 0xD800 + (rest >> 10));
+                append_three(out, 0xDC00 + (rest & 0x3FF));
+            }
         }
         return out;
     }
 
+    static void append_three(std::string &out, uint32_t code) {
+        out += static_cast<char>(0xE0 | (code >> 12));
+        out += static_cast<char>(0x80 | ((code >> 6) & 0x3F));
+        out += static_cast<char>(0x80 | (code & 0x3F));
+    }
+
     void option(const char *name, const char *value) { mpv_set_option_string(mpv_, name, value); }
     void observe(const char *name, uint64_t id, mpv_format format) { mpv_observe_property(mpv_, id, name, format); }
     void set_string(const char *name, const std::string &value) { mpv_set_property_string(mpv_, name, value.c_str()); }
@@ -306,25 +525,72 @@ class Player {
                 if (start > 0.0) set_double("time-pos", start);
             }
             if (event->event_id == MPV_EVENT_END_FILE) {
+                const auto *end = static_cast<mpv_event_end_file *>(event->data);
                 std::lock_guard lock(state_mutex_);
+                // The end of the file `loadfile` is replacing, not of the one it
+                // is loading. Reporting it would hand every reader an episode
+                // that ended before it started.
+                if (state_.loading) continue;
                 state_.ended = true;
+                state_.end_reason = end ? end_reason_of(end->reason) : EndReason::Other;
             } else if (event->event_id == MPV_EVENT_START_FILE) {
                 std::lock_guard lock(state_mutex_);
+                state_.loading = false;
                 state_.ended = false;
+                state_.end_reason = EndReason::None;
+            } else if (event->event_id == MPV_EVENT_SEEK) {
+                std::lock_guard lock(state_mutex_);
+                state_.seeking = true;
+            } else if (event->event_id == MPV_EVENT_PLAYBACK_RESTART) {
+                // The seek is *visibly* done here, not when it was issued.
+                std::lock_guard lock(state_mutex_);
+                state_.seeking = false;
+            } else if (event->event_id == MPV_EVENT_LOG_MESSAGE) {
+                record_log(*static_cast<mpv_event_log_message *>(event->data));
             } else if (event->event_id == MPV_EVENT_PROPERTY_CHANGE) {
                 update_property(*static_cast<mpv_event_property *>(event->data));
             }
         }
     }
 
+    /// Keep the first error of the open file, not the last.
+    ///
+    /// A failure cascades — one unreadable header produces a dozen follow-on
+    /// complaints — and the first line is the one that names the cause. Cleared
+    /// by [take_error], which is how the UI consumes it.
+    ///
+    /// Only mpv's own errors. Everything libavcodec and libavformat complain
+    /// about arrives under an `ffmpeg/…` prefix, and mpv is the thing that
+    /// decides whether any of it mattered: a decoder that refuses to
+    /// initialise is an error there and a fallback here, so surfacing those
+    /// puts a dialog over a file that goes on to play perfectly. When one of
+    /// them really is fatal mpv says so itself, under a prefix of its own.
+    void record_log(const mpv_event_log_message &message) {
+        if (!message.text) return;
+        if (message.prefix && !std::strncmp(message.prefix, "ffmpeg", 6)) return;
+        std::lock_guard lock(state_mutex_);
+        if (!error_.empty()) return;
+        error_.assign(message.text);
+        while (!error_.empty() && (error_.back() == '\n' || error_.back() == '\r')) error_.pop_back();
+    }
+
     void update_property(const mpv_event_property &property) {
         if (!property.data) return;
         std::lock_guard lock(state_mutex_);
-        if (!std::strcmp(property.name, "time-pos")) state_.position = *static_cast<double *>(property.data);
-        else if (!std::strcmp(property.name, "duration")) state_.duration = *static_cast<double *>(property.data);
-        else if (!std::strcmp(property.name, "volume")) state_.volume = *static_cast<double *>(property.data);
+        // `volume`, `mute` and `pause` belong to the core and carry across a
+        // load; the rest describe the open file, and a reading of them that
+        // arrives mid-load is the outgoing episode's clock under the incoming
+        // episode's name.
+        if (!std::strcmp(property.name, "volume")) state_.volume = *static_cast<double *>(property.data);
         else if (!std::strcmp(property.name, "pause")) state_.paused = *static_cast<int *>(property.data);
         else if (!std::strcmp(property.name, "mute")) state_.muted = *static_cast<int *>(property.data);
+        else if (state_.loading) return;
+        else if (!std::strcmp(property.name, "time-pos")) state_.position = *static_cast<double *>(property.data);
+        else if (!std::strcmp(property.name, "duration")) state_.duration = *static_cast<double *>(property.data);
+        else if (!std::strcmp(property.name, "video-params/dw")) state_.video_width = static_cast<double>(*static_cast<int64_t *>(property.data));
+        else if (!std::strcmp(property.name, "video-params/dh")) state_.video_height = static_cast<double>(*static_cast<int64_t *>(property.data));
+        else if (!std::strcmp(property.name, "paused-for-cache")) state_.buffering = *static_cast<int *>(property.data);
+        else if (!std::strcmp(property.name, "cache-buffering-state")) state_.cache_percent = static_cast<double>(*static_cast<int64_t *>(property.data));
     }
 
     static void render_update(void *opaque) noexcept {
@@ -336,6 +602,15 @@ class Player {
         });
     }
 
+    /// Owns EGL and the mpv render context for the life of the player.
+    ///
+    /// Both are set up here rather than on the first surface attach, and neither
+    /// depends on there being a window: a pbuffer is enough to make a context
+    /// current, and `vo_libmpv` only needs *some* consumer. That is what makes
+    /// audio playback with no surface — the screen off, the app backgrounded —
+    /// structurally possible; before this, `load` waited five seconds for a
+    /// render context that only a visible SurfaceView could ever create, and
+    /// then failed.
     void render_loop() {
         EGLDisplay display = EGL_NO_DISPLAY;
         EGLContext context = EGL_NO_CONTEXT;
@@ -343,6 +618,7 @@ class Player {
         EGLSurface pbuffer = EGL_NO_SURFACE;
         EGLConfig config = nullptr;
         ANativeWindow *window = nullptr;
+        if (initialize_egl(display, context, config, pbuffer)) initialize_renderer();
         while (running_.load()) {
             std::unique_lock lock(render_mutex_);
             render_cv_.wait(lock, [this] { return !running_.load() || surface_changed_ || frame_ready_.load(); });
@@ -353,18 +629,31 @@ class Player {
                 if (window) ANativeWindow_release(window);
                 window = pending_window_;
                 pending_window_ = nullptr;
-                if (window && display == EGL_NO_DISPLAY && !initialize_egl(display, context, config, pbuffer)) {
+                if (window && display == EGL_NO_DISPLAY) {
+                    // EGL failed at startup and playback is audio-only. Keep the
+                    // window rather than the surface: nothing here can retry.
                     ANativeWindow_release(window);
                     window = nullptr;
                 }
                 if (window) {
                     surface = eglCreateWindowSurface(display, config, window, nullptr);
                     eglMakeCurrent(display, surface, surface, context);
-                    initialize_renderer();
                 }
             }
             const bool draw = frame_ready_.exchange(false);
             lock.unlock();
+            // With no window there is still a frame to consume. `vo_libmpv`
+            // expects its host to keep draining, and a video thread with no
+            // consumer stalls — which is why video came back out of sync with
+            // audio after the screen had been off.
+            if (draw && surface == EGL_NO_SURFACE && render_) {
+                eglMakeCurrent(display, pbuffer, pbuffer, context);
+                if (mpv_render_context_update(render_) & MPV_RENDER_UPDATE_FRAME) {
+                    int skip = 1;
+                    mpv_render_param params[] = {{MPV_RENDER_PARAM_SKIP_RENDERING, &skip}, {MPV_RENDER_PARAM_INVALID, nullptr}};
+                    mpv_render_context_render(render_, params);
+                }
+            }
             if (draw && surface != EGL_NO_SURFACE && render_) {
                 eglMakeCurrent(display, surface, surface, context);
                 if (mpv_render_context_update(render_) & MPV_RENDER_UPDATE_FRAME) {
@@ -394,18 +683,40 @@ class Player {
         if (pending_window_) { ANativeWindow_release(pending_window_); pending_window_ = nullptr; }
     }
 
+    /// All of EGL, or none of it.
+    ///
+    /// Leaving a display initialised behind a failed context is what made a
+    /// partial failure permanent: the retry guard is "is there a display", so a
+    /// half-built state reads as success forever and every later attach uses an
+    /// uninitialised config and `EGL_NO_CONTEXT`. Unwinding here keeps the guard
+    /// honest, and `eglGetError` says which step failed instead of leaving a
+    /// black screen with nothing in the log.
     bool initialize_egl(EGLDisplay &display, EGLContext &context, EGLConfig &config, EGLSurface &pbuffer) {
+        const auto fail = [&](const char *step) {
+            __android_log_print(ANDROID_LOG_ERROR, "pstr-mpv", "%s failed: 0x%04x", step, eglGetError());
+            if (pbuffer != EGL_NO_SURFACE) eglDestroySurface(display, pbuffer);
+            if (context != EGL_NO_CONTEXT) eglDestroyContext(display, context);
+            if (display != EGL_NO_DISPLAY) eglTerminate(display);
+            display = EGL_NO_DISPLAY;
+            context = EGL_NO_CONTEXT;
+            pbuffer = EGL_NO_SURFACE;
+            config = nullptr;
+            return false;
+        };
         display = eglGetDisplay(EGL_DEFAULT_DISPLAY);
-        if (display == EGL_NO_DISPLAY || !eglInitialize(display, nullptr, nullptr)) return false;
+        if (display == EGL_NO_DISPLAY) return fail("eglGetDisplay");
+        if (!eglInitialize(display, nullptr, nullptr)) return fail("eglInitialize");
         const EGLint attributes[] = {EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT, EGL_SURFACE_TYPE, EGL_WINDOW_BIT | EGL_PBUFFER_BIT, EGL_RED_SIZE, 8, EGL_GREEN_SIZE, 8, EGL_BLUE_SIZE, 8, EGL_NONE};
         EGLint count = 0;
-        if (!eglChooseConfig(display, attributes, &config, 1, &count) || count == 0) return false;
+        if (!eglChooseConfig(display, attributes, &config, 1, &count) || count == 0) return fail("eglChooseConfig");
         const EGLint context_attributes[] = {EGL_CONTEXT_CLIENT_VERSION, 2, EGL_NONE};
         context = eglCreateContext(display, config, EGL_NO_CONTEXT, context_attributes);
-        if (context == EGL_NO_CONTEXT) return false;
+        if (context == EGL_NO_CONTEXT) return fail("eglCreateContext");
         const EGLint pbuffer_attributes[] = {EGL_WIDTH, 1, EGL_HEIGHT, 1, EGL_NONE};
         pbuffer = eglCreatePbufferSurface(display, config, pbuffer_attributes);
-        return pbuffer != EGL_NO_SURFACE && eglMakeCurrent(display, pbuffer, pbuffer, context);
+        if (pbuffer == EGL_NO_SURFACE) return fail("eglCreatePbufferSurface");
+        if (!eglMakeCurrent(display, pbuffer, pbuffer, context)) return fail("eglMakeCurrent");
+        return true;
     }
 
     void initialize_renderer() {
@@ -426,6 +737,8 @@ class Player {
     std::thread renderer_;
     mutable std::mutex state_mutex_;
     PlaybackState state_;
+    /// The first error mpv logged about the open file, until it is consumed.
+    std::string error_;
     std::mutex render_mutex_;
     std::condition_variable render_cv_;
     ANativeWindow *pending_window_ = nullptr;
@@ -465,13 +778,33 @@ bool utf8(JNIEnv *env, jstring value, std::string &result) {
 void reject_null_surface(JNIEnv *env) noexcept {
     c_boundary([=] {
         jclass type = env->FindClass("java/lang/IllegalArgumentException");
-        if (type) env->ThrowNew(type, "surface must not be null");
+        if (!type) return;
+        env->ThrowNew(type, "surface must not be null");
+        // FindClass hands back a local reference, and this is called from a
+        // long-lived attached thread where the frame is not popped for us.
+        env->DeleteLocalRef(type);
     });
 }
 
 } // namespace
 
-extern "C" JNIEXPORT jlong JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_nativeCreate(JNIEnv *, jobject) noexcept {
+/// FFmpeg's MediaCodec decoders call into Android's Java API, and they can only
+/// reach it through a JavaVM handed to them explicitly — there is no way for
+/// them to discover one. Without this, every hardware decoder fails to open
+/// with "hevc_mediacodec: No Java virtual machine has been registered" and
+/// playback falls back to software decoding, which on a phone means a hot
+/// device and dropped frames on anything above 1080p.
+///
+/// mpv-android's own JNI layer does this in its `create` entry point; this
+/// library replaces that layer, so the registration has to happen here. The
+/// loader calls this once per process before any native method, which is
+/// earlier than any decoder can run.
+extern "C" JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
+    av_jni_set_java_vm(vm, nullptr);
+    return JNI_VERSION_1_6;
+}
+
+extern "C" JNIEXPORT jlong JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_nativeCreate(JNIEnv *, jclass) noexcept {
     return c_boundary<jlong>(0, [] {
         auto player = std::make_unique<Player>();
         return player->valid() ? reinterpret_cast<jlong>(player.release()) : 0;
@@ -513,6 +846,9 @@ extern "C" JNIEXPORT void JNICALL Java_io_narl_protonstream_playback_NativeMpvHo
 extern "C" JNIEXPORT void JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_nativeVolume(JNIEnv *, jobject, jlong h, jdouble value) noexcept {
     c_boundary([=] { if (auto *p = from(h)) p->volume(value); });
 }
+extern "C" JNIEXPORT void JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_nativeSpeed(JNIEnv *, jobject, jlong h, jdouble value) noexcept {
+    c_boundary([=] { if (auto *p = from(h)) p->speed(value); });
+}
 extern "C" JNIEXPORT void JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_nativeMute(JNIEnv *, jobject, jlong h, jboolean value) noexcept {
     c_boundary([=] { if (auto *p = from(h)) p->mute(value == JNI_TRUE); });
 }
@@ -527,19 +863,38 @@ extern "C" JNIEXPORT jdoubleArray JNICALL Java_io_narl_protonstream_playback_Nat
         const auto state = from(h) ? from(h)->state() : PlaybackState{};
         const jdouble values[] = {state.position, state.duration, state.volume,
                                   state.paused ? 1.0 : 0.0, state.muted ? 1.0 : 0.0,
-                                  state.ended ? 1.0 : 0.0};
-        jdoubleArray result = env->NewDoubleArray(6);
+                                  state.ended ? 1.0 : 0.0,
+                                  static_cast<jdouble>(state.generation),
+                                  state.video_width, state.video_height,
+                                  static_cast<jdouble>(state.end_reason),
+                                  state.buffering ? 1.0 : 0.0, state.cache_percent,
+                                  state.seeking ? 1.0 : 0.0};
+        constexpr jsize kFields = 13;
+        jdoubleArray result = env->NewDoubleArray(kFields);
         if (!result) return static_cast<jdoubleArray>(nullptr);
-        env->SetDoubleArrayRegion(result, 0, 6, values);
+        env->SetDoubleArrayRegion(result, 0, kFields, values);
         if (env->ExceptionCheck()) return static_cast<jdoubleArray>(nullptr);
         return result;
     });
 }
+extern "C" JNIEXPORT jstring JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_nativeTakeError(JNIEnv *env, jobject, jlong h) noexcept {
+    return c_boundary<jstring>(nullptr, [=]() -> jstring {
+        auto *player = from(h);
+        if (!player) return nullptr;
+        const std::string error = player->take_error();
+        return error.empty() ? nullptr : string(env, error);
+    });
+}
 extern "C" JNIEXPORT jstring JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_nativeTracks(JNIEnv *env, jobject, jlong h) noexcept {
     return c_boundary<jstring>(nullptr, [=] {
         return string(env, from(h) ? from(h)->tracks_json() : "[]");
     });
 }
+extern "C" JNIEXPORT jstring JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_nativeChapters(JNIEnv *env, jobject, jlong h) noexcept {
+    return c_boundary<jstring>(nullptr, [=] {
+        return string(env, from(h) ? from(h)->chapters_json() : "[]");
+    });
+}
 extern "C" JNIEXPORT void JNICALL Java_io_narl_protonstream_playback_NativeMpvHost_pstrAndroidStreamRelease(JNIEnv *, jobject, jlong handle) noexcept {
     c_boundary([=] { pstr_android_stream_release(static_cast<uint64_t>(handle)); });
 }

android/app/src/main/cpp/pstr_mpv.h

@@ -8,6 +8,9 @@ extern "C" {
 #endif
 int64_t pstr_android_stream_read(uint64_t handle, uint64_t offset, void *buffer, size_t length);
 int64_t pstr_android_stream_size(uint64_t handle);
+/// Interrupts an in-flight `pstr_android_stream_read`. A cancel with no reader
+/// waiting is dropped, so this is safe to call speculatively.
+void pstr_android_stream_cancel(uint64_t handle);
 void pstr_android_stream_release(uint64_t handle);
 #ifdef __cplusplus
 }

android/app/src/main/java/io/narl/protonstream/MainActivity.kt

@@ -1,72 +1,189 @@
 package io.narl.protonstream
 
 import android.Manifest
-import android.content.pm.PackageManager
-import android.os.Bundle
-import android.os.Build
+import android.app.PendingIntent
 import android.app.PictureInPictureParams
+import android.app.RemoteAction
+import android.content.BroadcastReceiver
 import android.content.ComponentName
 import android.content.Context
 import android.content.Intent
+import android.content.IntentFilter
 import android.content.ServiceConnection
+import android.content.pm.PackageManager
+import android.content.res.Configuration
+import android.graphics.Rect
+import android.graphics.drawable.Icon
+import android.os.Build
+import android.os.Bundle
 import android.os.IBinder
 import android.util.Rational
 import androidx.activity.ComponentActivity
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
 import androidx.activity.result.contract.ActivityResultContracts
-import io.narl.protonstream.ui.ProtonStreamApp
-import io.narl.protonstream.ui.theme.ProtonStreamTheme
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.snapshotFlow
+import androidx.core.content.ContextCompat
+import androidx.core.graphics.drawable.toDrawable
+import androidx.core.view.WindowCompat
+import androidx.lifecycle.lifecycleScope
+import io.narl.protonstream.native.NativeRuntime
+import io.narl.protonstream.playback.MpvPlaybackState
 import io.narl.protonstream.playback.NativeMpvHost
 import io.narl.protonstream.playback.PlaybackService
-import androidx.compose.runtime.mutableStateOf
 import io.narl.protonstream.settings.SettingsStore
+import io.narl.protonstream.ui.ProtonStreamApp
+import io.narl.protonstream.ui.theme.AppearanceState
+import io.narl.protonstream.ui.theme.ProtonStreamTheme
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.flatMapLatest
+import kotlinx.coroutines.flow.flowOf
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.launch
+import uniffi.pstr_android.PaletteRecord
 
 class MainActivity : ComponentActivity() {
     private val playerHost = mutableStateOf<NativeMpvHost?>(null)
+    private val inPictureInPicture = mutableStateOf(false)
+    /**
+     * Whether a bind is outstanding, which is what has to be unbound.
+     *
+     * Set when `bindService` is called rather than when the connection arrives:
+     * an activity destroyed while the bind is still pending owes the system an
+     * `unbindService` just the same, and `onServiceConnected` may never run.
+     */
     private var bound = false
     private val playbackConnection = object : ServiceConnection {
         override fun onServiceConnected(name: ComponentName?, service: IBinder?) {
             playerHost.value = (service as PlaybackService.PlaybackBinder).host
-            bound = true
         }
         override fun onServiceDisconnected(name: ComponentName?) {
             playerHost.value = null
-            bound = false
         }
     }
+
+    /**
+     * The transport behind the buttons Android draws over the PiP window.
+     *
+     * A broadcast rather than a service intent: PiP is one of the states in
+     * which a background service start is refused, and the receiver is
+     * registered for as long as the activity that owns the window exists.
+     */
+    private val pictureInPictureControls = object : BroadcastReceiver() {
+        override fun onReceive(context: Context?, intent: Intent?) {
+            val host = playerHost.value ?: return
+            when (intent?.getStringExtra(EXTRA_CONTROL)) {
+                CONTROL_PLAY -> host.setPaused(false)
+                CONTROL_PAUSE -> host.setPaused(true)
+                CONTROL_NEXT -> host.onSkipNext?.invoke()
+                CONTROL_PREVIOUS -> host.onSkipPrevious?.invoke()
+            }
+        }
+    }
+
     private val notificationPermission = registerForActivityResult(
         ActivityResultContracts.RequestPermission(),
     ) { /* Downloads remain usable; Android suppresses their notifications if denied. */ }
 
+    @OptIn(ExperimentalCoroutinesApi::class)
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
+        // Before anything draws. The palette decides the window's own
+        // background and which way round the system bars' icons go, and both
+        // are wrong for a frame if they are set from a composition instead.
+        // Infallible by construction — an unreadable theme file resolves to the
+        // shipped default rather than throwing.
+        runCatching { NativeRuntime.storedPalette() }.onSuccess(AppearanceState::seed)
         enableEdgeToEdge()
-        bindService(Intent(this, PlaybackService::class.java), playbackConnection, Context.BIND_AUTO_CREATE)
+        // Re-applied on every change, not just at startup: picking Latte from
+        // the settings page has to turn the status bar's icons dark in the same
+        // frame the page behind them turns light.
+        lifecycleScope.launch {
+            AppearanceState.palette.filterNotNull().distinctUntilChanged().collect(::dressWindow)
+        }
+        bound = bindService(
+            Intent(this, PlaybackService::class.java),
+            playbackConnection,
+            Context.BIND_AUTO_CREATE,
+        )
+        ContextCompat.registerReceiver(
+            this,
+            pictureInPictureControls,
+            IntentFilter(ACTION_PIP_CONTROL),
+            ContextCompat.RECEIVER_NOT_EXPORTED,
+        )
         if (
             Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
             checkSelfPermission(Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED
         ) {
             notificationPermission.launch(Manifest.permission.POST_NOTIFICATIONS)
         }
+        // Auto-enter has to be armed *before* the gesture that would use it:
+        // building the params inside onUserLeaveHint is too late for the swipe
+        // home that gesture navigation sends, which never calls it. Re-register
+        // whenever the picture's shape or the transport's does.
+        lifecycleScope.launch {
+            snapshotFlow { playerHost.value }
+                .flatMapLatest { host -> host?.state ?: flowOf(null) }
+                .map { state -> PictureInPictureShape.of(state) }
+                .distinctUntilChanged()
+                .collect { shape -> runCatching { setPictureInPictureParams(shape.params()) } }
+        }
         setContent {
             ProtonStreamTheme {
-                ProtonStreamApp(playerHost.value)
+                ProtonStreamApp(playerHost.value, inPictureInPicture.value)
             }
         }
     }
 
+    /**
+     * The parts of the window Compose does not reach: the background behind the
+     * whole activity, and the polarity of the system bars' icons.
+     *
+     * The background matters for the frames before and between compositions —
+     * the launch frame, and a rotation. It used to be a hex literal in
+     * `themes.xml`, which meant every cold start showed a colour from one
+     * flavour regardless of which one was chosen.
+     *
+     * The icons matter because the app ships a light flavour. Pinned dark, as
+     * they were, Latte drew white status-bar icons onto a near-white page.
+     */
+    private fun dressWindow(palette: PaletteRecord) {
+        window.setBackgroundDrawable(palette.background.toInt().toDrawable())
+        WindowCompat.getInsetsController(window, window.decorView).apply {
+            isAppearanceLightStatusBars = palette.light
+            isAppearanceLightNavigationBars = palette.light
+        }
+    }
+
     override fun onUserLeaveHint() {
         super.onUserLeaveHint()
+        // The backstop for launchers that still send this instead of arming
+        // auto-enter. Entering twice is not an error; not entering at all is.
         if (playerHost.value?.hasActivePlayback == true && !isInPictureInPictureMode) {
-            enterPictureInPictureMode(
-                PictureInPictureParams.Builder().setAspectRatio(Rational(16, 9)).setAutoEnterEnabled(true).build(),
-            )
+            runCatching {
+                enterPictureInPictureMode(PictureInPictureShape.of(playerHost.value?.state?.value).params())
+            }
         }
     }
 
+    override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean, newConfig: Configuration) {
+        super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
+        // The window is now a thumbnail with its own controls. Anything the
+        // player would draw over it — the transport, the title bar, the skip
+        // offer — is unreadable at that size and covers the picture.
+        inPictureInPicture.value = isInPictureInPictureMode
+    }
+
     override fun onDestroy() {
-        if (bound) unbindService(playbackConnection)
+        runCatching { unregisterReceiver(pictureInPictureControls) }
+        if (bound) {
+            unbindService(playbackConnection)
+            bound = false
+        }
         super.onDestroy()
     }
 
@@ -80,4 +197,81 @@ class MainActivity : ComponentActivity() {
             playerHost.value?.stop()
         }
     }
+
+    /** Everything the PiP window's shape depends on, and nothing that polls. */
+    private data class PictureInPictureShape(
+        val active: Boolean,
+        val paused: Boolean,
+        val width: Int,
+        val height: Int,
+    ) {
+        companion object {
+            fun of(state: MpvPlaybackState?): PictureInPictureShape = PictureInPictureShape(
+                active = state != null && state.duration > 0.0 && !state.ended,
+                paused = state?.paused != false,
+                width = state?.videoWidth?.toInt() ?: 0,
+                height = state?.videoHeight?.toInt() ?: 0,
+            )
+        }
+    }
+
+    private fun PictureInPictureShape.params(): PictureInPictureParams =
+        PictureInPictureParams.Builder()
+            .setAspectRatio(aspectRatio(width, height))
+            .setAutoEnterEnabled(active)
+            .setSeamlessResizeEnabled(false)
+            // The player owns the whole window, so the picture's rectangle is
+            // the window's. Without it the transition into PiP cross-fades from
+            // a screenshot instead of shrinking the video that is already there.
+            .setSourceRectHint(windowBounds())
+            .setActions(
+                listOf(
+                    remoteAction(android.R.drawable.ic_media_previous, "Previous episode", CONTROL_PREVIOUS, 11),
+                    if (paused) remoteAction(android.R.drawable.ic_media_play, "Play", CONTROL_PLAY, 12)
+                    else remoteAction(android.R.drawable.ic_media_pause, "Pause", CONTROL_PAUSE, 13),
+                    remoteAction(android.R.drawable.ic_media_next, "Next episode", CONTROL_NEXT, 14),
+                ),
+            )
+            .build()
+
+    private fun windowBounds(): Rect = window.decorView.let { Rect(0, 0, it.width, it.height) }
+
+    private fun remoteAction(icon: Int, label: String, control: String, requestCode: Int): RemoteAction =
+        RemoteAction(
+            Icon.createWithResource(this, icon),
+            label,
+            label,
+            PendingIntent.getBroadcast(
+                this,
+                requestCode,
+                Intent(ACTION_PIP_CONTROL).setPackage(packageName).putExtra(EXTRA_CONTROL, control),
+                PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+            ),
+        )
+
+    private companion object {
+        const val ACTION_PIP_CONTROL = "io.narl.protonstream.PIP_CONTROL"
+        const val EXTRA_CONTROL = "control"
+        const val CONTROL_PLAY = "play"
+        const val CONTROL_PAUSE = "pause"
+        const val CONTROL_NEXT = "next"
+        const val CONTROL_PREVIOUS = "previous"
+
+        /**
+         * Android refuses a window narrower than 1:2.39 or taller than 2.39:1,
+         * and refuses the request outright rather than clamping it — so a
+         * 2.40:1 scope release would take PiP away entirely.
+         */
+        fun aspectRatio(width: Int, height: Int): Rational {
+            if (width <= 0 || height <= 0) return Rational(16, 9)
+            val ratio = width.toDouble() / height
+            return when {
+                ratio > MAX_RATIO -> Rational(239, 100)
+                ratio < 1 / MAX_RATIO -> Rational(100, 239)
+                else -> Rational(width, height)
+            }
+        }
+
+        const val MAX_RATIO = 2.39
+    }
 }

android/app/src/main/java/io/narl/protonstream/download/DownloadCoordinator.kt

@@ -1,37 +1,151 @@
 package io.narl.protonstream.download
 
 import android.content.Context
+import android.os.StatFs
 import androidx.work.Constraints
 import androidx.work.ExistingWorkPolicy
 import androidx.work.NetworkType
+import androidx.work.OneTimeWorkRequest
 import androidx.work.OneTimeWorkRequestBuilder
 import androidx.work.WorkManager
 import androidx.work.workDataOf
 import io.narl.protonstream.settings.SettingsStore
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
 import uniffi.pstr_android.EpisodeRecord
 
 object DownloadCoordinator {
-    fun enqueue(context: Context, episode: EpisodeRecord) {
-        enqueue(
-            context,
-            RetainedDownload(episode.shareId, episode.volumeId, episode.linkId, episode.label),
-            ExistingWorkPolicy.KEEP,
-        )
-    }
+    /**
+     * Where bulk queueing runs.
+     *
+     * Callers are click handlers, and "Download show" on a long series is a
+     * WorkManager enqueue per episode — each of which writes to its own
+     * database. On the main thread that is an ANR waiting for a long enough
+     * series.
+     */
+    private val queueing = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    fun enqueue(context: Context, episode: EpisodeRecord) = enqueue(context, listOf(episode))
 
     fun resume(context: Context, download: RetainedDownload) {
         enqueue(context, download, ExistingWorkPolicy.REPLACE)
     }
 
     private fun enqueue(context: Context, download: RetainedDownload, policy: ExistingWorkPolicy) {
-        DownloadStateStore(context).put(
-            download.copy(status = RetainedDownload.STATUS_QUEUED, error = null),
+        val queued = download.copy(status = RetainedDownload.STATUS_QUEUED, error = null)
+        DownloadStateStore(context).put(queued)
+        WorkManager.getInstance(context).enqueueUniqueWork(
+            workName(download.shareId, download.linkId),
+            policy,
+            request(queued, SettingsStore(context).wifiOnly),
         )
-        val request = OneTimeWorkRequestBuilder<OfflineDownloadWorker>()
+    }
+
+    fun enqueue(context: Context, episodes: Iterable<EpisodeRecord>) {
+        val wanted = episodes.filterNot(EpisodeRecord::offline).toList()
+        if (wanted.isEmpty()) return
+        val application = context.applicationContext
+        queueing.launch {
+            val wifiOnly = SettingsStore(application).wifiOnly
+            val store = DownloadStateStore(application)
+            val manager = WorkManager.getInstance(application)
+            // Space is checked once for the whole request, against its total.
+            // Queueing a season that cannot fit and discovering it episode by
+            // episode at ENOSPC is how the app fills its own database's disk.
+            val room = roomFor(application, wanted.sumOf { it.size?.toLong() ?: 0L })
+            val downloads = wanted.map { episode ->
+                RetainedDownload(
+                    episode.shareId,
+                    episode.volumeId,
+                    episode.linkId,
+                    episode.label,
+                    total = episode.size?.toLong() ?: 0L,
+                    status = if (room) RetainedDownload.STATUS_QUEUED else RetainedDownload.STATUS_FAILED,
+                    error = if (room) null else "Not enough free space",
+                )
+            }
+            store.putAll(downloads)
+            if (!room) return@launch
+            downloads.forEach { download ->
+                manager.enqueueUniqueWork(
+                    workName(download.shareId, download.linkId),
+                    ExistingWorkPolicy.KEEP,
+                    request(download, wifiOnly),
+                )
+            }
+        }
+    }
+
+    /**
+     * Whether [bytes] plus working room will fit where offline files are kept.
+     *
+     * `setRequiresStorageNotLow` only holds work back at Android's own low-storage
+     * threshold, which a single episode can cross on its own. An unknown size —
+     * zero — is allowed through: refusing a download because the catalog has no
+     * size for it would be worse than the ENOSPC it is guarding against.
+     */
+    private fun roomFor(context: Context, bytes: Long): Boolean {
+        if (bytes <= 0) return true
+        val available = runCatching { StatFs(context.filesDir.path).availableBytes }.getOrNull() ?: return true
+        return available - bytes >= STORAGE_HEADROOM
+    }
+
+    /**
+     * Re-apply the network constraint to work that is already queued.
+     *
+     * Constraints are baked in at enqueue time, so turning "Wi-Fi only" on after
+     * queueing a season did nothing to that season — it downloaded over cellular
+     * on the way out of the house, which is the one moment the setting exists
+     * for. Running work is left alone: WorkManager stops it on its own when the
+     * new constraint stops being met.
+     */
+    fun applyNetworkPolicy(context: Context) {
+        val application = context.applicationContext
+        queueing.launch {
+            val wifiOnly = SettingsStore(application).wifiOnly
+            val manager = WorkManager.getInstance(application)
+            DownloadStateStore(application).records()
+                .filter { it.status == RetainedDownload.STATUS_QUEUED || it.status == RetainedDownload.STATUS_RUNNING }
+                .forEach { download ->
+                    manager.enqueueUniqueWork(
+                        workName(download.shareId, download.linkId),
+                        ExistingWorkPolicy.REPLACE,
+                        request(download, wifiOnly),
+                    )
+                }
+        }
+    }
+
+    fun pause(context: Context, download: RetainedDownload) =
+        setStatus(context, download, RetainedDownload.STATUS_PAUSED)
+
+    fun cancel(context: Context, download: RetainedDownload) =
+        setStatus(context, download, RetainedDownload.STATUS_CANCELLED)
+
+    /**
+     * The status write goes before the work is cancelled, and through `update`
+     * rather than `put`: the running worker is writing progress into the same
+     * record, and a whole-record `put` from a screen's stale copy would both
+     * lose that progress and race the worker's own read-modify-write.
+     */
+    private fun setStatus(context: Context, download: RetainedDownload, status: String) {
+        DownloadStateStore(context).update(download.shareId, download.linkId) { stored ->
+            (stored ?: download).copy(status = status, error = null)
+        }
+        WorkManager.getInstance(context).cancelUniqueWork(workName(download.shareId, download.linkId))
+    }
+
+    private fun request(download: RetainedDownload, wifiOnly: Boolean): OneTimeWorkRequest =
+        OneTimeWorkRequestBuilder<OfflineDownloadWorker>()
             .setConstraints(
-                Constraints.Builder().setRequiredNetworkType(
-                    requiredNetworkType(SettingsStore(context).wifiOnly),
-                ).build(),
+                Constraints.Builder()
+                    .setRequiredNetworkType(requiredNetworkType(wifiOnly))
+                    // A download that fills the disk takes the app's own
+                    // database down with it; the `.part` file makes waiting free.
+                    .setRequiresStorageNotLow(true)
+                    .build(),
             )
             .setInputData(
                 workDataOf(
@@ -45,26 +159,6 @@ object DownloadCoordinator {
             .addTag("$EPISODE_TAG${download.label}")
             .addTag(shareTag(download.shareId))
             .build()
-        WorkManager.getInstance(context).enqueueUniqueWork(
-            workName(download.shareId, download.linkId),
-            policy,
-            request,
-        )
-    }
-
-    fun enqueue(context: Context, episodes: Iterable<EpisodeRecord>) {
-        episodes.filterNot(EpisodeRecord::offline).forEach { enqueue(context, it) }
-    }
-
-    fun pause(context: Context, download: RetainedDownload) {
-        DownloadStateStore(context).put(download.copy(status = RetainedDownload.STATUS_PAUSED, error = null))
-        WorkManager.getInstance(context).cancelUniqueWork(workName(download.shareId, download.linkId))
-    }
-
-    fun cancel(context: Context, download: RetainedDownload) {
-        DownloadStateStore(context).put(download.copy(status = RetainedDownload.STATUS_CANCELLED))
-        WorkManager.getInstance(context).cancelUniqueWork(workName(download.shareId, download.linkId))
-    }
 
     fun shareTag(shareId: String) = "$SHARE_TAG$shareId"
     fun workName(shareId: String, linkId: String) = "offline-$shareId-$linkId"
@@ -72,6 +166,9 @@ object DownloadCoordinator {
     const val TAG = "offline-download"
     const val EPISODE_TAG = "offline-episode:"
     private const val SHARE_TAG = "offline-share:"
+
+    /** Free space to leave behind a download, for the catalog and the caches. */
+    private const val STORAGE_HEADROOM = 256L * 1024 * 1024
 }
 
 internal fun requiredNetworkType(wifiOnly: Boolean): NetworkType =

android/app/src/main/java/io/narl/protonstream/download/DownloadStateStore.kt

@@ -35,18 +35,59 @@ class DownloadStateStore(context: Context) {
     fun get(shareId: String, linkId: String): RetainedDownload? =
         preferences.getString(key(shareId, linkId), null)?.let { runCatching { decode(it) }.getOrNull() }
 
-    fun put(record: RetainedDownload) {
-        preferences.edit().putString(record.key, encode(record)).commit()
+    fun put(record: RetainedDownload) = synchronized(WRITES) {
+        edit { putString(record.key, encode(record)) }
     }
 
-    fun remove(shareId: String, linkId: String) {
-        preferences.edit().remove(key(shareId, linkId)).commit()
+    /**
+     * Read-modify-write one record, excluding every other writer.
+     *
+     * The worker's progress update reads the stored record to decide whether the
+     * viewer has paused, then writes it back. `pause()` is another writer, and
+     * without this a `put` landing between those two halves puts `RUNNING` back
+     * over `PAUSED` — after which the worker's own cancellation handler sees a
+     * status that is not `PAUSED` and records `CANCELLED`. The pause is simply
+     * lost, which is the visible bug.
+     *
+     * Returning null from [change] leaves the record alone.
+     */
+    fun update(shareId: String, linkId: String, change: (RetainedDownload?) -> RetainedDownload?) =
+        synchronized(WRITES) {
+            change(get(shareId, linkId))?.let { edit { putString(it.key, encode(it)) } }
+        }
+
+    /**
+     * Write a whole queue in one go.
+     *
+     * Queueing a season is one call, not one per episode: `commit()` per record
+     * on a 200-episode series was 200 synchronous fsyncs, and the callers are
+     * click handlers.
+     */
+    fun putAll(records: Collection<RetainedDownload>) = synchronized(WRITES) {
+        edit { records.forEach { putString(it.key, encode(it)) } }
     }
 
-    fun removeShare(shareId: String) {
-        val edit = preferences.edit()
-        records().filter { it.shareId == shareId }.forEach { edit.remove(it.key) }
-        edit.commit()
+    fun remove(shareId: String, linkId: String) = synchronized(WRITES) {
+        edit { remove(key(shareId, linkId)) }
+    }
+
+    /** Forget every retained download. Callers cancel the work first. */
+    fun clear() = synchronized(WRITES) { edit { clear() } }
+
+    fun removeShare(shareId: String) = synchronized(WRITES) {
+        edit { records().filter { it.shareId == shareId }.forEach { remove(it.key) } }
+    }
+
+    /**
+     * `apply()`, not `commit()`.
+     *
+     * The in-memory map is updated before this returns, so a read that follows a
+     * write in the same process still sees it; only the disk write is deferred,
+     * and losing the newest progress reading to a kill is not worth an fsync on
+     * whichever thread happened to be writing.
+     */
+    private inline fun edit(block: android.content.SharedPreferences.Editor.() -> Unit) {
+        preferences.edit().apply(block).apply()
     }
 
     private fun encode(record: RetainedDownload) = JSONObject()
@@ -78,5 +119,11 @@ class DownloadStateStore(context: Context) {
 
     private companion object {
         const val NAME = "offline_download_state"
+
+        /**
+         * One lock for the whole process. Instances of this class are created
+         * ad hoc from a `Context`, so the lock cannot live on one of them.
+         */
+        val WRITES = Any()
     }
 }

android/app/src/main/java/io/narl/protonstream/download/OfflineDownloadWorker.kt

@@ -4,6 +4,7 @@ import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.content.pm.ServiceInfo
 import android.content.Context
+import android.os.SystemClock
 import androidx.core.app.NotificationCompat
 import androidx.work.CoroutineWorker
 import androidx.work.Data
@@ -23,6 +24,7 @@ class OfflineDownloadWorker(
     parameters: WorkerParameters,
 ) : CoroutineWorker(appContext, parameters) {
     override suspend fun doWork(): Result {
+        createNotificationChannel()
         setForeground(createForegroundInfo(0))
         val shareId = inputData.getString(KEY_SHARE_ID) ?: return Result.failure(error("missing share"))
         val volumeId = inputData.getString(KEY_VOLUME_ID) ?: return Result.failure(error("missing volume"))
@@ -35,20 +37,43 @@ class OfflineDownloadWorker(
         store.put(retained)
 
         val observer = object : DownloadObserver {
+            private var reportedAt = 0L
+            private var reportedPercent = -1
+
+            /**
+             * Called once per 4 MiB block — a dozen times a second on a fast
+             * link, each one a WorkManager database write, a notification post
+             * and a preferences write. Nothing the viewer can see changes that
+             * often, so a report is only made when the percentage moves or a
+             * second has passed. The final one is never suppressed.
+             */
             override fun onProgress(downloaded: ULong, total: ULong) {
                 val percent = if (total == 0UL) 0 else ((downloaded * 100UL) / total).toInt()
+                val now = SystemClock.elapsedRealtime()
+                val complete = total > 0UL && downloaded >= total
+                if (!complete && percent == reportedPercent && now - reportedAt < PROGRESS_INTERVAL_MS) {
+                    return
+                }
+                reportedAt = now
+                reportedPercent = percent
                 setProgressAsync(workDataOf(KEY_DOWNLOADED to downloaded.toLong(), KEY_TOTAL to total.toLong()))
                 setForegroundAsync(createForegroundInfo(percent))
-                val requested = store.get(shareId, linkId)
-                val requestedStatus = requested?.status
-                retained = (requested ?: retained).copy(
-                    downloaded = downloaded.toLong(),
-                    total = total.toLong(),
-                    status = if (requestedStatus == RetainedDownload.STATUS_PAUSED ||
-                        requestedStatus == RetainedDownload.STATUS_CANCELLED
-                    ) requestedStatus else RetainedDownload.STATUS_RUNNING,
-                )
-                store.put(retained)
+                // Under the store's lock: `pause()` is a concurrent writer, and
+                // this read-modify-write used to put RUNNING back over the
+                // viewer's PAUSED and then report the download as cancelled.
+                store.update(shareId, linkId) { stored ->
+                    val current = stored ?: retained
+                    current.copy(
+                        downloaded = downloaded.toLong(),
+                        total = total.toLong(),
+                        status = when (current.status) {
+                            RetainedDownload.STATUS_PAUSED,
+                            RetainedDownload.STATUS_CANCELLED,
+                            -> current.status
+                            else -> RetainedDownload.STATUS_RUNNING
+                        },
+                    ).also { retained = it }
+                }
             }
 
             override fun isCancelled(): Boolean = isStopped
@@ -62,9 +87,12 @@ class OfflineDownloadWorker(
             },
             onFailure = { failure ->
                 if (isStopped) {
-                    val current = store.get(shareId, linkId) ?: retained
-                    if (current.status != RetainedDownload.STATUS_PAUSED) {
-                        store.put(current.copy(status = RetainedDownload.STATUS_CANCELLED))
+                    // A pause is also a stop. Under the lock, so the record read
+                    // here is the one the write lands on.
+                    store.update(shareId, linkId) { stored ->
+                        val current = stored ?: retained
+                        current.takeIf { it.status != RetainedDownload.STATUS_PAUSED }
+                            ?.copy(status = RetainedDownload.STATUS_CANCELLED)
                     }
                     Result.failure(error("cancelled"))
                 } else if (runAttemptCount < MAX_RETRIES) {
@@ -79,11 +107,14 @@ class OfflineDownloadWorker(
         )
     }
 
-    private fun createForegroundInfo(progress: Int): ForegroundInfo {
-        val manager = applicationContext.getSystemService(NotificationManager::class.java)
-        manager.createNotificationChannel(
+    /** Once per run, rather than once per 4 MiB block. */
+    private fun createNotificationChannel() {
+        applicationContext.getSystemService(NotificationManager::class.java).createNotificationChannel(
             NotificationChannel(CHANNEL_ID, "Offline downloads", NotificationManager.IMPORTANCE_LOW),
         )
+    }
+
+    private fun createForegroundInfo(progress: Int): ForegroundInfo {
         val notification = NotificationCompat.Builder(applicationContext, CHANNEL_ID)
             .setSmallIcon(io.narl.protonstream.R.drawable.ic_launcher_foreground)
             .setContentTitle("Making episode available offline")
@@ -109,6 +140,9 @@ class OfflineDownloadWorker(
         const val KEY_TOTAL = "total"
         private const val MAX_RETRIES = 3
         private const val CHANNEL_ID = "offline-downloads"
+
+        /** Shortest gap between two identical-looking progress reports. */
+        private const val PROGRESS_INTERVAL_MS = 1_000L
     }
 }
 

android/app/src/main/java/io/narl/protonstream/native/KeystoreSecretStore.kt

@@ -2,6 +2,7 @@ package io.narl.protonstream.native
 
 import android.content.Context
 import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyPermanentlyInvalidatedException
 import android.security.keystore.KeyProperties
 import android.util.Base64
 import java.security.KeyStore
@@ -10,22 +11,44 @@ import javax.crypto.KeyGenerator
 import javax.crypto.SecretKey
 import javax.crypto.spec.GCMParameterSpec
 import uniffi.pstr_android.AndroidSecretStore
+import uniffi.pstr_android.BridgeException
 
-/** Encrypts share fragments and passwords before they reach app preferences. */
+/**
+ * Encrypts share fragments and passwords before they reach app preferences.
+ *
+ * Every failure here leaves as a [BridgeException]. Raw Java exceptions crossing
+ * the FFI have no mapping on the Rust side, and an unmapped callback exception
+ * is a panic on whichever thread was calling — including a tokio worker holding
+ * a download. What the caller does about it is a separate question; being told
+ * at all is this class's part.
+ */
 class KeystoreSecretStore(context: Context) : AndroidSecretStore {
     private val preferences = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
     private val keyStore = KeyStore.getInstance("AndroidKeyStore").apply { load(null) }
 
-    override fun set(key: String, value: String) {
-        val cipher = Cipher.getInstance(TRANSFORMATION)
-        cipher.init(Cipher.ENCRYPT_MODE, encryptionKey())
-        val encrypted = cipher.doFinal(value.toByteArray(Charsets.UTF_8))
-        val payload = cipher.iv + encrypted
+    override fun set(key: String, value: String) = bridging("store credential") {
+        val payload = try {
+            seal(value)
+        } catch (invalidated: KeyPermanentlyInvalidatedException) {
+            // A lockscreen change or a device restore retires the key. Nothing
+            // it sealed can be read again — and nothing new can be sealed with
+            // it either, so re-entering a link would fail here rather than
+            // restoring access. Everything the old key held is already lost, so
+            // replacing it costs nothing that is not gone.
+            keyStore.deleteEntry(KEY_ALIAS)
+            seal(value)
+        }
         check(preferences.edit().putString(key, Base64.encodeToString(payload, Base64.NO_WRAP)).commit())
     }
 
-    override fun get(key: String): String? {
-        val encoded = preferences.getString(key, null) ?: return null
+    private fun seal(value: String): ByteArray {
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        cipher.init(Cipher.ENCRYPT_MODE, encryptionKey())
+        return cipher.iv + cipher.doFinal(value.toByteArray(Charsets.UTF_8))
+    }
+
+    override fun get(key: String): String? = bridging("read credential") {
+        val encoded = preferences.getString(key, null) ?: return@bridging null
         val payload = Base64.decode(encoded, Base64.NO_WRAP)
         require(payload.size > IV_SIZE) { "Invalid encrypted credential" }
         val cipher = Cipher.getInstance(TRANSFORMATION)
@@ -34,13 +57,23 @@ class KeystoreSecretStore(context: Context) : AndroidSecretStore {
             encryptionKey(),
             GCMParameterSpec(TAG_BITS, payload.copyOfRange(0, IV_SIZE)),
         )
-        return cipher.doFinal(payload.copyOfRange(IV_SIZE, payload.size)).toString(Charsets.UTF_8)
+        cipher.doFinal(payload.copyOfRange(IV_SIZE, payload.size)).toString(Charsets.UTF_8)
     }
 
-    override fun delete(key: String) {
+    override fun delete(key: String) = bridging("delete credential") {
         check(preferences.edit().remove(key).commit())
     }
 
+    private fun <T> bridging(action: String, block: () -> T): T = try {
+        block()
+    } catch (error: BridgeException) {
+        throw error
+    } catch (error: Exception) {
+        // The message, never the stack trace: this reaches a snackbar, and the
+        // trace is both unreadable there and a description of app internals.
+        throw BridgeException.Failure("Could not $action: ${error.message ?: error::class.java.simpleName}")
+    }
+
     private fun encryptionKey(): SecretKey {
         (keyStore.getKey(KEY_ALIAS, null) as? SecretKey)?.let { return it }
         return KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore").run {

android/app/src/main/java/io/narl/protonstream/native/NativeRuntime.kt

@@ -6,20 +6,30 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
 import uniffi.pstr_android.AndroidEngine
 import uniffi.pstr_android.AndroidPaths
+import uniffi.pstr_android.PaletteRecord
 
 /** Process-wide owner of the Rust engine; records and decrypted media remain app-private. */
 object NativeRuntime {
     private lateinit var appContext: Context
     @Volatile private var instance: AndroidEngine? = null
 
+    /**
+     * Whether Android's certificate verifier came up.
+     *
+     * False means every HTTPS request will fail validation, which otherwise
+     * surfaces much later as an unexplained certificate error against a share.
+     */
+    @Volatile var tlsReady: Boolean = false
+        private set
+
     fun initialize(context: Context) {
         System.loadLibrary("pstr_android")
-        initTls(context)
+        tlsReady = initTls(context)
         appContext = context.applicationContext
     }
 
     /** Initializes Android's certificate verifier before Proton networking. */
-    private external fun initTls(context: Context)
+    private external fun initTls(context: Context): Boolean
 
     suspend fun engine(): AndroidEngine = withContext(Dispatchers.IO) {
         instance ?: synchronized(this@NativeRuntime) {
@@ -27,14 +37,24 @@ object NativeRuntime {
         }
     }
 
-    private fun createEngine(): AndroidEngine {
+    /**
+     * The stored palette, without building the engine.
+     *
+     * Callable from the main thread, and meant to be: it is the only palette
+     * read early enough to decide what the first frame is painted in, and
+     * [engine] is not — that opens SQLite, spins a Tokio runtime and unlocks a
+     * Keystore key. This reads one small JSON file and resolves it.
+     */
+    fun storedPalette(): PaletteRecord = uniffi.pstr_android.storedPalette(paths())
+
+    private fun paths(): AndroidPaths {
         check(::appContext.isInitialized) { "NativeRuntime is not initialized" }
         val config = File(appContext.noBackupFilesDir, "config")
         val data = File(appContext.filesDir, "data")
         val cache = File(appContext.cacheDir, "stream")
-        return AndroidEngine(
-            AndroidPaths(config.absolutePath, data.absolutePath, cache.absolutePath),
-            KeystoreSecretStore(appContext),
-        )
+        return AndroidPaths(config.absolutePath, data.absolutePath, cache.absolutePath)
     }
+
+    private fun createEngine(): AndroidEngine =
+        AndroidEngine(paths(), KeystoreSecretStore(appContext))
 }

android/app/src/main/java/io/narl/protonstream/playback/LibmpvPlayerSurface.kt

@@ -1,343 +0,0 @@
-package io.narl.protonstream.playback
-
-import android.view.Surface
-import android.view.SurfaceHolder
-import android.view.SurfaceView
-import androidx.compose.foundation.background
-import androidx.compose.foundation.layout.Box
-import androidx.compose.foundation.layout.fillMaxSize
-import androidx.compose.foundation.layout.fillMaxWidth
-import androidx.compose.foundation.layout.padding
-import androidx.compose.foundation.layout.Row
-import androidx.compose.foundation.layout.Column
-import androidx.compose.foundation.layout.Arrangement
-import androidx.compose.foundation.layout.heightIn
-import androidx.compose.foundation.lazy.LazyColumn
-import androidx.compose.foundation.lazy.items
-import androidx.compose.animation.AnimatedVisibility
-import androidx.compose.animation.fadeIn
-import androidx.compose.animation.fadeOut
-import androidx.compose.foundation.clickable
-import androidx.compose.material3.AlertDialog
-import androidx.compose.material3.Button
-import androidx.compose.material3.OutlinedButton
-import androidx.compose.material3.Slider
-import androidx.compose.material3.MaterialTheme
-import androidx.compose.material3.Text
-import androidx.compose.material3.Icon
-import androidx.compose.material3.IconButton
-import androidx.compose.material.icons.Icons
-import androidx.compose.material.icons.filled.PlayArrow
-import androidx.compose.material.icons.filled.Pause
-import androidx.compose.material.icons.filled.Fullscreen
-import androidx.compose.material.icons.filled.FullscreenExit
-import androidx.compose.material.icons.filled.VolumeUp
-import androidx.compose.material.icons.filled.VolumeOff
-import androidx.compose.material.icons.filled.Subtitles
-import androidx.compose.material.icons.filled.Audiotrack
-import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
-import androidx.compose.runtime.LaunchedEffect
-import androidx.compose.runtime.remember
-import androidx.compose.runtime.rememberCoroutineScope
-import androidx.compose.runtime.collectAsState
-import androidx.compose.runtime.getValue
-import androidx.compose.runtime.mutableStateOf
-import androidx.compose.runtime.setValue
-import androidx.compose.ui.Alignment
-import androidx.compose.ui.Modifier
-import androidx.compose.ui.graphics.Color
-import androidx.compose.ui.unit.dp
-import androidx.compose.ui.viewinterop.AndroidView
-import io.narl.protonstream.native.NativeRuntime
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.delay
-import kotlinx.coroutines.launch
-import kotlinx.coroutines.withContext
-import uniffi.pstr_android.AndroidEngine
-import uniffi.pstr_android.AndroidStream
-import uniffi.pstr_android.EpisodeRecord
-import kotlin.math.roundToInt
-
-/** Exact seekable stream contract a bundled libmpv JNI adapter must consume. */
-class RustStreamSession(
-    private val episode: EpisodeRecord,
-) {
-    private var engine: AndroidEngine? = null
-    private var stream: AndroidStream? = null
-    private var handle: ULong? = null
-    private var streamSize: ULong? = null
-
-    suspend fun open(): RustStreamSession = withContext(Dispatchers.IO) {
-        val openedEngine = NativeRuntime.engine()
-        engine = openedEngine
-        stream = openedEngine.openStream(episode.shareId, episode.volumeId, episode.linkId).also {
-            streamSize = it.size()
-            handle = it.nativeHandle()
-        }
-        this@RustStreamSession
-    }
-
-    fun nativeHandle(): ULong = checkNotNull(handle) { "stream is not published" }
-
-    fun size(): ULong = checkNotNull(streamSize) { "stream is not open" }
-
-    fun releaseNative(host: LibmpvHost) {
-        handle?.let(host::releaseNativeStream)
-        handle = null
-        streamSize = null
-        stream = null
-    }
-
-    /** The native player now owns the published token until stop/end/close. */
-    fun transferToPlayer() {
-        handle = null
-        streamSize = null
-        stream = null
-    }
-
-    suspend fun closeEngine() = withContext(Dispatchers.IO) {
-        engine?.releaseStream(episode.shareId, episode.volumeId, episode.linkId)
-        engine = null
-    }
-}
-
-/** Implement only in the variant that bundles a pinned libmpv native artifact. */
-interface LibmpvHost {
-    fun attachSurface(surface: Surface)
-    fun detachSurface()
-    /** Consumes the opaque handle through pstr_android_stream_{read,size}. */
-    suspend fun play(
-        nativeHandle: ULong,
-        size: ULong,
-        startPosition: Double = 0.0,
-        audioLanguage: String? = null,
-        subtitleLanguage: String? = null,
-        subtitles: Boolean = true,
-    )
-    /** Calls pstr_android_stream_release exactly once for a published handle. */
-    fun releaseNativeStream(nativeHandle: ULong)
-}
-
-private data class PlaybackStartup(
-    val nativeHandle: ULong,
-    val size: ULong,
-    val startPosition: Double,
-    val audioLanguage: String?,
-    val subtitleLanguage: String?,
-    val subtitles: Boolean,
-)
-
-@Composable
-fun LibmpvPlayerSurface(
-    titleKey: String,
-    episode: EpisodeRecord,
-    host: LibmpvHost? = null,
-    isFullscreen: Boolean = false,
-    onToggleFullscreen: () -> Unit = {}
-) {
-    if (host == null) {
-        Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
-            Text("Playback is unavailable: this build does not include libmpv.", color = Color.White)
-        }
-        return
-    }
-
-    val scope = rememberCoroutineScope()
-    var playbackError by remember(sessionKey(episode)) { mutableStateOf<String?>(null) }
-    val session = remember(episode.shareId, episode.linkId) {
-        RustStreamSession(episode)
-    }
-    LaunchedEffect(session, host) {
-        runCatching {
-            val startup = withContext(Dispatchers.IO) {
-                session.open()
-                val engine = NativeRuntime.engine()
-                val preferences = engine.titleTrackPreferences(titleKey)
-                val watch = engine.watchState(episode.shareId, episode.linkId)
-                PlaybackStartup(
-                    nativeHandle = session.nativeHandle(),
-                    size = session.size(),
-                    startPosition = watch?.positionSecs ?: 0.0,
-                    audioLanguage = preferences.audioLanguage,
-                    subtitleLanguage = preferences.subtitleLanguage,
-                    subtitles = preferences.subtitles,
-                )
-            }
-            host.play(
-                startup.nativeHandle, startup.size, startup.startPosition,
-                startup.audioLanguage, startup.subtitleLanguage, startup.subtitles,
-            )
-            session.transferToPlayer()
-        }.onFailure { playbackError = it.message ?: "Playback failed" }
-    }
-    DisposableEffect(session, host) {
-        onDispose {
-            host.detachSurface()
-            session.releaseNative(host)
-            scope.launch { session.closeEngine() }
-        }
-    }
-    
-    var showControls by remember { mutableStateOf(true) }
-    LaunchedEffect(showControls) {
-        if (showControls) {
-            delay(4000)
-            showControls = false
-        }
-    }
-
-    Box(Modifier.fillMaxSize().clickable(
-        interactionSource = remember { androidx.compose.foundation.interaction.MutableInteractionSource() },
-        indication = null,
-        onClick = { showControls = !showControls }
-    )) {
-        AndroidView(
-            modifier = Modifier.fillMaxSize(),
-            factory = { context ->
-                SurfaceView(context).apply {
-                    holder.addCallback(object : SurfaceHolder.Callback {
-                        override fun surfaceCreated(holder: SurfaceHolder) = host.attachSurface(holder.surface)
-                        override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) = host.attachSurface(holder.surface)
-                        override fun surfaceDestroyed(holder: SurfaceHolder) = host.detachSurface()
-                    })
-                }
-            },
-        )
-        AnimatedVisibility(
-            visible = showControls,
-            modifier = Modifier.align(Alignment.BottomCenter),
-            enter = fadeIn(),
-            exit = fadeOut()
-        ) {
-            if (host is NativeMpvHost) PlayerControls(
-                titleKey,
-                episode,
-                host,
-                isFullscreen,
-                onToggleFullscreen
-            )
-        }
-        playbackError?.let { message ->
-            Text(message, color = Color.White, modifier = Modifier.align(Alignment.Center).background(Color.Black.copy(alpha = 0.8f)).padding(16.dp))
-        }
-    }
-}
-
-private fun sessionKey(episode: EpisodeRecord) = "${episode.shareId}:${episode.linkId}"
-
-@Composable
-private fun PlayerControls(
-    titleKey: String,
-    episode: EpisodeRecord,
-    host: NativeMpvHost,
-    isFullscreen: Boolean,
-    onToggleFullscreen: () -> Unit,
-    modifier: Modifier = Modifier
-) {
-    val state by host.state.collectAsState()
-    val tracks by host.tracks.collectAsState()
-    val scope = rememberCoroutineScope()
-    var choosing by remember { mutableStateOf<String?>(null) }
-    LaunchedEffect(state.position.roundToInt() / 5) {
-        if (state.duration > 0.0) withContext(Dispatchers.IO) {
-            NativeRuntime.engine().saveWatchState(
-                episode.shareId, episode.linkId, state.position.coerceAtMost(state.duration), state.duration,
-                state.ended || state.position >= state.duration * 0.9,
-            )
-        }
-    }
-    Column(modifier.fillMaxWidth().background(Color.Black.copy(alpha = 0.68f)).padding(12.dp)) {
-        Slider(
-            value = state.position.toFloat().coerceIn(0f, state.duration.toFloat().coerceAtLeast(1f)),
-            onValueChange = { host.seek(it.toDouble()) },
-            valueRange = 0f..state.duration.toFloat().coerceAtLeast(1f),
-        )
-        Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween, verticalAlignment = Alignment.CenterVertically) {
-            IconButton(onClick = { host.setPaused(!state.paused) }) { 
-                Icon(if (state.paused) Icons.Default.PlayArrow else Icons.Default.Pause, contentDescription = "Play/Pause", tint = Color.White) 
-            }
-            Text("${formatTime(state.position)} / ${formatTime(state.duration)}", color = Color.White)
-            Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
-                IconButton(onClick = { host.setMuted(!state.muted) }) { 
-                    Icon(if (state.muted) Icons.Default.VolumeOff else Icons.Default.VolumeUp, contentDescription = "Mute", tint = Color.White) 
-                }
-                IconButton(onClick = onToggleFullscreen) { 
-                    Icon(if (isFullscreen) Icons.Default.FullscreenExit else Icons.Default.Fullscreen, contentDescription = "Fullscreen", tint = Color.White) 
-                }
-            }
-        }
-        Row(horizontalArrangement = Arrangement.spacedBy(8.dp), verticalAlignment = Alignment.CenterVertically) {
-            IconButton(onClick = { choosing = "audio" }) {
-                Icon(Icons.Default.Audiotrack, contentDescription = "Audio", tint = Color.White)
-            }
-            IconButton(onClick = { choosing = "sub" }) {
-                Icon(Icons.Default.Subtitles, contentDescription = "Subtitles", tint = Color.White)
-            }
-            Text(
-                "Audio: ${tracks.firstOrNull { it.type == "audio" && it.selected }?.label ?: "default"}  •  " +
-                "Subtitles: ${tracks.firstOrNull { it.type == "sub" && it.selected }?.label ?: "off"}",
-                color = Color.White,
-                style = MaterialTheme.typography.bodySmall
-            )
-        }
-    }
-    choosing?.let { type ->
-        TrackChooser(
-            type = type,
-            tracks = tracks.filter { it.type == type },
-            onDismiss = { choosing = null },
-            onSelect = { selected ->
-                host.selectTrack(selected)
-                choosing = null
-                scope.launch(Dispatchers.IO) {
-                    val engine = NativeRuntime.engine()
-                    val old = engine.titleTrackPreferences(titleKey)
-                    engine.setTitleTrackPreferences(
-                        titleKey,
-                        if (type == "audio") old.copy(audioLanguage = selected?.language?.takeIf(String::isNotBlank))
-                        else old.copy(
-                            subtitleLanguage = selected?.language?.takeIf(String::isNotBlank),
-                            subtitles = selected != null,
-                        ),
-                    )
-                }
-            },
-        )
-    }
-}
-
-@Composable
-private fun TrackChooser(
-    type: String,
-    tracks: List<MpvTrack>,
-    onDismiss: () -> Unit,
-    onSelect: (MpvTrack?) -> Unit,
-) {
-    AlertDialog(
-        onDismissRequest = onDismiss,
-        title = { Text(if (type == "audio") "Audio track" else "Subtitle track") },
-        text = {
-            LazyColumn(Modifier.fillMaxWidth().heightIn(max = 420.dp)) {
-                if (type == "sub") {
-                    item {
-                        OutlinedButton(onClick = { onSelect(null) }, Modifier.fillMaxWidth()) {
-                            Text(if (tracks.none(MpvTrack::selected)) "✓  Off" else "Off")
-                        }
-                    }
-                }
-                items(tracks, key = MpvTrack::id) { track ->
-                    OutlinedButton(onClick = { onSelect(track) }, Modifier.fillMaxWidth()) {
-                        Text(if (track.selected) "✓  ${track.label}" else track.label)
-                    }
-                }
-            }
-        },
-        confirmButton = { Button(onClick = onDismiss) { Text("Close") } },
-    )
-}
-
-private fun formatTime(seconds: Double): String {
-    val total = seconds.coerceAtLeast(0.0).roundToInt()
-    return "%d:%02d".format(total / 60, total % 60)
-}

android/app/src/main/java/io/narl/protonstream/playback/NativeMpvHost.kt

@@ -1,6 +1,7 @@
 package io.narl.protonstream.playback
 
 import android.view.Surface
+import io.narl.protonstream.ui.ThumbnailSource
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
@@ -16,6 +17,31 @@ import kotlinx.coroutines.withContext
 import org.json.JSONArray
 import java.util.concurrent.locks.ReentrantLock
 import kotlin.concurrent.withLock
+import uniffi.pstr_android.ChapterPlan
+import uniffi.pstr_android.ChapterRecord
+import uniffi.pstr_android.chapterPlan
+
+/**
+ * Why the open file ended, mirroring `pstr_player::EndReason` so both clients
+ * agree on what "finished" means.
+ *
+ * Only [Eof] is an episode watched to the end. Treating the others as one — a
+ * stop, a shutdown, a failed demux — is what marks an episode that never played
+ * as watched and autoplays past it.
+ */
+enum class EndReason {
+    None,
+    Eof,
+    Stopped,
+    Quit,
+    Failed,
+    Other,
+    ;
+
+    companion object {
+        fun of(value: Double): EndReason = entries.getOrElse(value.toInt()) { Other }
+    }
+}
 
 data class MpvPlaybackState(
     val position: Double = 0.0,
@@ -24,6 +50,53 @@ data class MpvPlaybackState(
     val paused: Boolean = true,
     val muted: Boolean = false,
     val ended: Boolean = false,
+    /** Meaningful only while [ended]; [EndReason.None] otherwise. */
+    val endReason: EndReason = EndReason.None,
+    /**
+     * Which episode this reading belongs to, or null before the first poll of a
+     * newly loaded file. Everything that *writes* per-episode state — resume
+     * position above all — must check this: one host serves every episode, and
+     * a reading attributed to the wrong one resumes the next episode where the
+     * last one stopped.
+     */
+    val media: String? = null,
+    /** The picture's display size, or zero until mpv has decoded enough to know. */
+    val videoWidth: Double = 0.0,
+    val videoHeight: Double = 0.0,
+    /**
+     * mpv has run out of buffered data and stopped to refill.
+     *
+     * Not the same as [paused], which is the viewer's doing. A frozen picture
+     * that nothing explains is indistinguishable from a hung app, which is what
+     * a network-backed stream looked like before this existed.
+     */
+    val buffering: Boolean = false,
+    /** How full the demuxer cache is while [buffering], 0–100. */
+    val cachePercent: Double = 0.0,
+    /** A seek has been issued but playback has not resumed at the new position. */
+    val seeking: Boolean = false,
+) {
+    /** Whether the picture is stopped for a reason the viewer did not choose. */
+    val stalled: Boolean get() = (buffering || seeking) && !paused && !ended
+}
+
+/**
+ * What is on screen, for the surfaces that are not the player.
+ *
+ * The media session, its notification and Picture-in-Picture all have to name
+ * the episode, and none of them can reach the composition that knows it. The
+ * player publishes this once per episode and they read it.
+ */
+data class NowPlaying(
+    val media: String,
+    val title: String,
+    val show: String?,
+    val detail: String?,
+    val artworkUrl: String?,
+    /** The file to pull a Proton thumbnail from when the provider has no poster. */
+    val artworkFile: ThumbnailSource?,
+    val hasPrevious: Boolean,
+    val hasNext: Boolean,
 )
 
 data class MpvTrack(
@@ -38,21 +111,61 @@ data class MpvTrack(
 }
 
 /** Process-local owner of the libmpv core. PlaybackService owns its lifetime. */
-class NativeMpvHost : LibmpvHost, AutoCloseable {
-    private val nativeHandle = nativeCreate().also { check(it != 0L) { "libmpv initialization failed" } }
+class NativeMpvHost private constructor(private val nativeHandle: Long) : LibmpvHost, AutoCloseable {
     private val lifecycle = ReentrantLock()
     @Volatile private var closed = false
     private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
     private val mutableState = MutableStateFlow(MpvPlaybackState())
     private val mutableTracks = MutableStateFlow(emptyList<MpvTrack>())
+    private val mutableChapters = MutableStateFlow(ChapterPlan(emptyList(), null))
+    private val mutableNowPlaying = MutableStateFlow<NowPlaying?>(null)
+    private val mutableAdvancing = MutableStateFlow(false)
+    private val mutableProblem = MutableStateFlow<String?>(null)
     private var poller: Job? = null
-    private var currentStreamHandle: Long? = null
+    /** The episode key and load generation the native player currently holds. */
+    @Volatile private var currentMedia: String? = null
+    @Volatile private var currentGeneration: Double = -1.0
+    @Volatile private var plannedFor: Pair<Double, Long>? = null
     var onPlaybackStarted: (() -> Unit)? = null
     var onStateChanged: ((MpvPlaybackState) -> Unit)? = null
     var onExplicitStop: (() -> Unit)? = null
+    /**
+     * Where a transport outside the player sends previous/next.
+     *
+     * The player owns which episode is open, so the notification, the lock
+     * screen and Picture-in-Picture cannot walk the playlist themselves. Both
+     * run on the main thread, which is where the player's state lives.
+     */
+    var onSkipPrevious: (() -> Unit)? = null
+    var onSkipNext: (() -> Unit)? = null
 
     val state: StateFlow<MpvPlaybackState> = mutableState.asStateFlow()
     val tracks: StateFlow<List<MpvTrack>> = mutableTracks.asStateFlow()
+    /** The open file's chapters, already resolved into openings and endings. */
+    val chapters: StateFlow<ChapterPlan> = mutableChapters.asStateFlow()
+    /** The episode the player has open, for every surface that has to name it. */
+    val nowPlaying: StateFlow<NowPlaying?> = mutableNowPlaying.asStateFlow()
+    /**
+     * True while the player is between episodes.
+     *
+     * The end of one episode and the start of the next are separated by a
+     * network round trip — opening the next revision's stream. The foreground
+     * service must not retire in that gap: with no foreground state left, the
+     * `startForeground` on the other side is a background start, which API 31+
+     * refuses outright.
+     */
+    val advancing: StateFlow<Boolean> = mutableAdvancing.asStateFlow()
+    /**
+     * What mpv last complained about, until the viewer dismisses it.
+     *
+     * Errors mpv reports are about the *file* — an unreadable header, a codec it
+     * has no decoder for — and reach nothing else: the play call has already
+     * returned successfully by the time they happen.
+     */
+    val problem: StateFlow<String?> = mutableProblem.asStateFlow()
+
+    /** Dismiss the current [problem]. */
+    fun clearProblem() { mutableProblem.value = null }
     val hasActivePlayback: Boolean get() = mutableState.value.duration > 0.0 && !mutableState.value.ended
 
     override fun attachSurface(surface: Surface) {
@@ -64,6 +177,7 @@ class NativeMpvHost : LibmpvHost, AutoCloseable {
     }
 
     override suspend fun play(
+        media: String,
         nativeHandle: ULong,
         size: ULong,
         startPosition: Double,
@@ -72,69 +186,172 @@ class NativeMpvHost : LibmpvHost, AutoCloseable {
         subtitles: Boolean,
     ) {
         check(size > 0uL) { "Cannot play an empty stream" }
-        withContext(Dispatchers.IO) {
-            val loaded = withOpenHandle {
-                nativeLoad(it, nativeHandle.toLong(), startPosition, audioLanguage, subtitleLanguage, subtitles).also { loaded ->
-                    if (loaded) {
-                        currentStreamHandle?.let(::pstrAndroidStreamRelease)
-                        currentStreamHandle = nativeHandle.toLong()
+        try {
+            withContext(Dispatchers.IO) {
+                val loaded = withOpenHandle {
+                    nativeLoad(it, nativeHandle.toLong(), startPosition, audioLanguage, subtitleLanguage, subtitles).also { loaded ->
+                        if (loaded) {
+                            // The outgoing stream is released by mpv closing it,
+                            // not from here: `loadfile` is asynchronous and its
+                            // demuxer may still be reading. `stream_close` in
+                            // `pstr_mpv.cpp` owns that release.
+                            //
+                            // The outgoing file's readings describe an episode
+                            // that is no longer open. Retire them here as well
+                            // as natively, so nothing observes them even once.
+                            currentMedia = media
+                            currentGeneration = withOpenHandle(::nativeState)?.generation() ?: -1.0
+                            mutableState.value = MpvPlaybackState(
+                                position = startPosition,
+                                volume = mutableState.value.volume,
+                                muted = mutableState.value.muted,
+                                media = media,
+                            )
+                            mutableProblem.value = null
+                            mutableTracks.value = emptyList()
+                            mutableChapters.value = ChapterPlan(emptyList(), null)
+                            plannedFor = null
+                        }
                     }
+                } ?: false
+                check(loaded) {
+                    "libmpv rejected the stream or no video surface was available"
                 }
-            } ?: false
-            check(loaded) {
-                "libmpv rejected the stream or no video surface was available"
             }
-        }
-        withOpenHandle {
-            onPlaybackStarted?.invoke()
-            startPolling()
+            withOpenHandle {
+                onPlaybackStarted?.invoke()
+                startPolling()
+            }
+        } finally {
+            // Whether the next episode arrived or failed to, the gap the
+            // foreground service was holding open is over.
+            mutableAdvancing.value = false
         }
     }
 
-    fun setPaused(paused: Boolean) { withOpenHandle { nativePause(it, paused) } }
+    /**
+     * Declare that the player is walking to another episode.
+     *
+     * Called before the stream for the next one is opened, and cleared when
+     * [play] returns either way — the window this covers is the one in which
+     * nothing is loaded and the service would otherwise conclude playback is
+     * finished.
+     */
+    fun beginTransition() { mutableAdvancing.value = true }
+
+    /** Names the open episode for the media session, its notification and PiP. */
+    fun publish(playing: NowPlaying?) { mutableNowPlaying.value = playing }
+
+    fun setPaused(paused: Boolean) {
+        // The native side writes the flag through, so every transport can flip
+        // now instead of on the next poll a quarter second from here.
+        val next = withOpenHandle {
+            nativePause(it, paused)
+            mutableState.value.copy(paused = paused).also { state -> mutableState.value = state }
+        } ?: return
+        onStateChanged?.invoke(next)
+    }
+
     fun seek(position: Double) { withOpenHandle { nativeSeek(it, position) } }
     fun setVolume(volume: Double) { withOpenHandle { nativeVolume(it, volume) } }
     fun setMuted(muted: Boolean) { withOpenHandle { nativeMute(it, muted) } }
+
+    /** Playback rate, 1.0 being the file's own. Clamped native-side. */
+    fun setSpeed(speed: Double) { withOpenHandle { nativeSpeed(it, speed) } }
     fun selectTrack(track: MpvTrack?) {
         val audio = track?.type == "audio"
         withOpenHandle { nativeSelectTrack(it, audio, track?.id ?: -1) }
         refreshTracks()
     }
 
-    /** Explicit user stop: stop media, release its stream, and retire the foreground service. */
+    /**
+     * Explicit user stop: stop media and retire the foreground service.
+     *
+     * The stream behind the open file is released by mpv closing it, which
+     * `stop` causes; releasing it from here would race that close.
+     */
     fun stop() {
         val callback = withOpenHandle {
             nativeStop(it)
-            currentStreamHandle?.let(::pstrAndroidStreamRelease)
-            currentStreamHandle = null
+            // Nothing loaded means nothing to attribute a reading to: a save
+            // issued after this must not land on the episode just stopped.
+            currentMedia = null
+            mutableAdvancing.value = false
+            mutableChapters.value = ChapterPlan(emptyList(), null)
+            mutableNowPlaying.value = null
             onExplicitStop
         }
         callback?.invoke()
     }
 
-    internal fun releaseEndedStream() {
-        withOpenHandle { currentStreamHandle?.let(::pstrAndroidStreamRelease); currentStreamHandle = null }
-    }
-
     override fun releaseNativeStream(nativeHandle: ULong) = pstrAndroidStreamRelease(nativeHandle.toLong())
 
     private fun startPolling() {
         if (poller?.isActive == true) return
-        poller = scope.launch {
+        // Off the main thread deliberately: `nativeState` and `nativeTracks`
+        // are synchronous `mpv_get_property` calls — five per track for the
+        // latter — that contend on the core lock the demuxer holds during a
+        // fetch. A poll that blocks there blocks the UI thread with it.
+        poller = scope.launch(Dispatchers.Default) {
             var tick = 0
             while (isActive) {
                 val values = withOpenHandle(::nativeState) ?: break
-                if (values.size >= 6) {
-                    val next = MpvPlaybackState(values[0], values[1], values[2], values[3] != 0.0, values[4] != 0.0, values[5] != 0.0)
+                if (values.size >= FIELDS) {
+                    val next = MpvPlaybackState(
+                        values[0], values[1], values[2],
+                        values[3] != 0.0, values[4] != 0.0, values[5] != 0.0,
+                        // Only a reading of the file this host was last asked
+                        // to load carries its episode's name.
+                        media = currentMedia.takeIf { values.generation() == currentGeneration },
+                        videoWidth = values[WIDTH],
+                        videoHeight = values[HEIGHT],
+                        endReason = EndReason.of(values[END_REASON]),
+                        buffering = values[BUFFERING] != 0.0,
+                        cachePercent = values[CACHE_PERCENT],
+                        seeking = values[SEEKING] != 0.0,
+                    )
                     mutableState.value = next
-                    onStateChanged?.invoke(next)
+                    // The listeners drive the media session and the player UI,
+                    // both of which are the main thread's.
+                    withContext(Dispatchers.Main) { onStateChanged?.invoke(next) }
+                    refreshChapters(next)
                 }
+                withOpenHandle(::nativeTakeError)?.let { mutableProblem.value = it }
                 if (tick++ % 4 == 0) refreshTracks()
                 delay(250)
             }
         }
     }
 
+    /**
+     * Re-read the chapters when there is a reason to: a different file, or a
+     * duration that has only just arrived. Both change the answer — the length
+     * of a chapter is what settles whether `Intro` is an opening or ten minutes
+     * of story — and neither changes again after that, so this settles quickly
+     * and then costs one comparison per poll.
+     */
+    private fun refreshChapters(state: MpvPlaybackState) {
+        val generation = currentGeneration
+        val wanted = state.duration to generation.toRawBits()
+        if (plannedFor == wanted) return
+        runCatching {
+            val encoded = withOpenHandle(::nativeChapters) ?: return
+            val values = JSONArray(encoded)
+            List(values.length()) { index ->
+                values.getJSONObject(index).run {
+                    ChapterRecord(
+                        index = getLong("index"),
+                        title = optString("title").takeIf(String::isNotBlank),
+                        start = getDouble("start"),
+                    )
+                }
+            }
+        }.onSuccess { chapters ->
+            plannedFor = wanted
+            mutableChapters.value = chapterPlan(chapters, state.duration.takeIf { it > 0.0 })
+        }
+    }
+
     private fun refreshTracks() {
         runCatching {
             val encoded = withOpenHandle(::nativeTracks) ?: return
@@ -149,16 +366,28 @@ class NativeMpvHost : LibmpvHost, AutoCloseable {
 
     override fun close() {
         scope.cancel()
-        lifecycle.withLock {
-            if (closed) return@withLock
+        val destroy = lifecycle.withLock {
+            if (closed) return@withLock false
             closed = true
             onPlaybackStarted = null
             onStateChanged = null
             onExplicitStop = null
-            nativeDestroy(nativeHandle)
-            currentStreamHandle?.let(::pstrAndroidStreamRelease)
-            currentStreamHandle = null
+            onSkipPrevious = null
+            onSkipNext = null
+            mutableNowPlaying.value = null
+            mutableAdvancing.value = false
+            true
         }
+        if (!destroy) return
+        // `mpv_terminate_destroy` joins mpv's demuxer thread, which may be
+        // parked in a block fetch over a degraded connection. This is called
+        // from Service.onDestroy — on the main thread — so waiting for it there
+        // is an ANR. `closed` is already set, so nothing new enters the handle;
+        // the lock is only to let a call that is already inside finish.
+        //
+        // Terminating the core closes the open file, and closing it releases the
+        // stream — after mpv's last read rather than during it.
+        Thread({ lifecycle.withLock { nativeDestroy(nativeHandle) } }, "pstr-mpv-teardown").start()
     }
 
     /** Serializes destruction against every JNI use of the raw Player pointer. */
@@ -166,7 +395,6 @@ class NativeMpvHost : LibmpvHost, AutoCloseable {
         if (closed) null else block(nativeHandle)
     }
 
-    private external fun nativeCreate(): Long
     private external fun nativeDestroy(handle: Long)
     private external fun nativeAttachSurface(handle: Long, surface: Surface)
     private external fun nativeDetachSurface(handle: Long)
@@ -174,17 +402,47 @@ class NativeMpvHost : LibmpvHost, AutoCloseable {
     private external fun nativePause(handle: Long, paused: Boolean)
     private external fun nativeSeek(handle: Long, position: Double)
     private external fun nativeVolume(handle: Long, volume: Double)
+    private external fun nativeSpeed(handle: Long, speed: Double)
     private external fun nativeMute(handle: Long, muted: Boolean)
     private external fun nativeSelectTrack(handle: Long, audio: Boolean, track: Long)
     private external fun nativeStop(handle: Long)
     private external fun nativeState(handle: Long): DoubleArray
-    private external fun nativeTracks(handle: Long): String
+    private external fun nativeTakeError(handle: Long): String?
+    // Nullable: `NewStringUTF` returns null when the string cannot be built,
+    // and a non-null declaration turns that into an NPE that `runCatching`
+    // swallows into a silently empty track list.
+    private external fun nativeTracks(handle: Long): String?
+    private external fun nativeChapters(handle: Long): String?
     private external fun pstrAndroidStreamRelease(handle: Long)
 
+    private fun DoubleArray.generation(): Double = getOrElse(GENERATION) { -1.0 }
+
     companion object {
+        /** Fields `nativeState` fills, in the order `pstr_mpv.cpp` writes them. */
+        private const val FIELDS = 13
+        private const val GENERATION = 6
+        private const val WIDTH = 7
+        private const val HEIGHT = 8
+        private const val END_REASON = 9
+        private const val BUFFERING = 10
+        private const val CACHE_PERCENT = 11
+        private const val SEEKING = 12
+
         init {
             System.loadLibrary("pstr_android")
             System.loadLibrary("pstr_mpv")
         }
+
+        /**
+         * A host over a live libmpv core, or null if libmpv would not start.
+         *
+         * Null rather than an exception: the service that owns this is created
+         * by the system, so a throw out of the constructor takes the process
+         * with it — and the app has a graceful "this build does not include
+         * libmpv" screen that a crash makes unreachable.
+         */
+        fun createOrNull(): NativeMpvHost? = nativeCreate().takeIf { it != 0L }?.let(::NativeMpvHost)
+
+        @JvmStatic private external fun nativeCreate(): Long
     }
 }

android/app/src/main/java/io/narl/protonstream/playback/PlaybackService.kt

@@ -5,7 +5,12 @@ import android.app.NotificationChannel
 import android.app.NotificationManager
 import android.app.PendingIntent
 import android.app.Service
+import android.content.BroadcastReceiver
+import android.content.Context
 import android.content.Intent
+import android.content.IntentFilter
+import android.graphics.Bitmap
+import android.graphics.drawable.Icon
 import android.media.AudioAttributes
 import android.media.AudioFocusRequest
 import android.media.AudioManager
@@ -14,38 +19,99 @@ import android.media.session.MediaSession
 import android.media.session.PlaybackState
 import android.os.Binder
 import android.os.IBinder
+import androidx.core.content.ContextCompat
 import io.narl.protonstream.MainActivity
+import io.narl.protonstream.R
 import io.narl.protonstream.settings.SettingsStore
+import io.narl.protonstream.ui.loadArtwork
+import io.narl.protonstream.ui.loadThumbnail
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withTimeoutOrNull
 
 /** Owns libmpv so audio survives Activity recreation, rotation and PiP. */
 class PlaybackService : Service() {
     inner class PlaybackBinder : Binder() {
-        val host: NativeMpvHost get() = this@PlaybackService.host
+        val host: NativeMpvHost? get() = this@PlaybackService.host
     }
 
-    private lateinit var host: NativeMpvHost
+    /**
+     * The libmpv core, or null when this build could not start one.
+     *
+     * Nullable rather than a `lateinit` that throws: the system creates this
+     * service, so a failure in its constructor takes the process down and makes
+     * the app's own "playback is unavailable" screen unreachable.
+     */
+    private var host: NativeMpvHost? = null
     private lateinit var mediaSession: MediaSession
     private lateinit var audioManager: AudioManager
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
     private var audioFocus: AudioFocusRequest? = null
-    private var notifiedPaused: Boolean? = null
+    /** Whether the pause on screen is this service's doing, not the viewer's. */
+    private var pausedForFocus = false
+    /** The volume before ducking, so the restore does not read a ducked one. */
+    private var beforeDucking: Double? = null
+    /**
+     * Pulling the headphone jack must not continue on the speaker.
+     *
+     * Android broadcasts this and expects every media app to handle it; the
+     * alternative is an episode playing out loud in a quiet room.
+     */
+    private val becomingNoisy = object : BroadcastReceiver() {
+        override fun onReceive(context: Context?, intent: Intent?) {
+            if (intent?.action == AudioManager.ACTION_AUDIO_BECOMING_NOISY) host?.setPaused(true)
+        }
+    }
     private var foregroundPlayback = false
     private var sessionPlayback = false
+    /**
+     * What the posted notification already says.
+     *
+     * The state poll runs four times a second and almost none of those readings
+     * change anything the shade shows. Re-posting on every one of them animates
+     * the media control and costs a binder round trip per tick, so the
+     * notification is rebuilt only when its own inputs move.
+     */
+    private var notified: NotificationShape? = null
+    /** The pending teardown, held so an episode transition can call it off. */
+    private var retire: Job? = null
+    /** The episode's artwork, and the source key it was fetched for. */
+    private var artwork: Pair<String, Bitmap>? = null
     private val binder = PlaybackBinder()
 
     override fun onCreate() {
         super.onCreate()
         createChannel()
+        ContextCompat.registerReceiver(
+            this,
+            becomingNoisy,
+            IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY),
+            ContextCompat.RECEIVER_NOT_EXPORTED,
+        )
         audioManager = getSystemService(AudioManager::class.java)
-        host = NativeMpvHost().apply {
+        host = NativeMpvHost.createOrNull()?.apply {
             onPlaybackStarted = {
-                requestAudioFocus()
+                // A refusal is rare — a call in progress — but playing over it
+                // is worse than not playing, and the viewer can simply press
+                // play again once the call ends.
+                if (!requestAudioFocus()) setPaused(true)
                 sessionPlayback = true
-                if (SettingsStore(this@PlaybackService).backgroundAudio) {
+                cancelRetire()
+                if (!foregroundPlayback && SettingsStore(this@PlaybackService).backgroundAudio) {
                     // Convert the bound service into a started foreground
                     // service only when the viewer opted to keep audio alive.
-                    startService(Intent(this@PlaybackService, PlaybackService::class.java))
-                    startForeground(NOTIFICATION_ID, notification(false))
-                    foregroundPlayback = true
+                    // Already-foreground is the ordinary case across an episode
+                    // transition, and re-entering costs a notification rebuild.
+                    foregroundPlayback = runCatching {
+                        startService(Intent(this@PlaybackService, PlaybackService::class.java))
+                        startForeground(NOTIFICATION_ID, notification(state.value, nowPlaying.value))
+                    }.isSuccess
                 }
                 mediaSession.isActive = true
             }
@@ -53,80 +119,213 @@ class PlaybackService : Service() {
             onExplicitStop = { retirePlayback() }
         }
         mediaSession = MediaSession(this, "proton-stream").apply {
+            setSessionActivity(openActivity())
             setCallback(object : MediaSession.Callback() {
-                override fun onPlay() = host.setPaused(false)
-                override fun onPause() = host.setPaused(true)
-                override fun onSeekTo(pos: Long) = host.seek(pos / 1_000.0)
-                override fun onStop() = host.stop()
+                override fun onPlay() { host?.setPaused(false) }
+                override fun onPause() { host?.setPaused(true) }
+                override fun onSeekTo(pos: Long) { host?.seek(pos / 1_000.0) }
+                override fun onStop() { host?.stop() }
+                override fun onSkipToNext() { host?.onSkipNext?.invoke() }
+                override fun onSkipToPrevious() { host?.onSkipPrevious?.invoke() }
             })
         }
+        // Artwork arrives after the episode does, and the shape of the transport
+        // changes with the playlist position, so the notification follows the
+        // published episode rather than being built once when playback starts.
+        val core = host ?: return
+        scope.launch {
+            core.nowPlaying.collect { playing ->
+                // Keyed by whichever source the episode has: with metadata off
+                // there is no provider poster, and Proton's own thumbnail is
+                // the only thing the shade can show.
+                artwork = playing?.let { episode ->
+                    val key = episode.artworkUrl ?: episode.artworkFile?.key ?: return@let null
+                    artwork?.takeIf { it.first == key }
+                        ?: (
+                            loadArtwork(this@PlaybackService, episode.artworkUrl)
+                                ?: loadThumbnail(episode.artworkFile)
+                            )?.let { key to it }
+                }
+                refreshSession(core.state.value, playing)
+            }
+        }
     }
 
     override fun onBind(intent: Intent?): IBinder = binder
 
     override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
         when (intent?.action) {
-            ACTION_PLAY -> host.setPaused(false)
-            ACTION_PAUSE -> host.setPaused(true)
-            ACTION_STOP -> host.stop()
+            ACTION_PLAY -> host?.setPaused(false)
+            ACTION_PAUSE -> host?.setPaused(true)
+            ACTION_PREVIOUS -> host?.onSkipPrevious?.invoke()
+            ACTION_NEXT -> host?.onSkipNext?.invoke()
+            ACTION_STOP -> host?.stop()
         }
         return START_NOT_STICKY
     }
 
     override fun onDestroy() {
+        scope.cancel()
+        runCatching { unregisterReceiver(becomingNoisy) }
         audioFocus?.let(audioManager::abandonAudioFocusRequest)
         mediaSession.release()
-        host.close()
+        host?.close()
         super.onDestroy()
     }
 
-    private fun requestAudioFocus() {
+    /**
+     * Take audio focus, and honour what the system says about it afterwards.
+     *
+     * The four cases are genuinely different and collapsing them is what made
+     * this feel broken: a phone call is transient and playback should come back
+     * by itself; a navigation prompt wants the volume down, not a pause; another
+     * media app taking over for good means giving the focus back rather than
+     * holding it; and a refusal means not playing at all.
+     */
+    private fun requestAudioFocus(): Boolean {
         audioFocus?.let(audioManager::abandonAudioFocusRequest)
         val request = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
             .setAudioAttributes(
                 AudioAttributes.Builder().setUsage(AudioAttributes.USAGE_MEDIA)
                     .setContentType(AudioAttributes.CONTENT_TYPE_MOVIE).build(),
             )
+            .setWillPauseWhenDucked(false)
             .setOnAudioFocusChangeListener { focus ->
                 when (focus) {
-                    AudioManager.AUDIOFOCUS_LOSS, AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> host.setPaused(true)
-                    AudioManager.AUDIOFOCUS_GAIN -> Unit
+                    AudioManager.AUDIOFOCUS_LOSS -> {
+                        pausedForFocus = false
+                        audioFocus?.let(audioManager::abandonAudioFocusRequest)
+                        audioFocus = null
+                        host?.setPaused(true)
+                    }
+                    AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
+                        // Only resume what this paused: a viewer who paused
+                        // before the phone rang expects it still paused after.
+                        pausedForFocus = host?.state?.value?.paused == false
+                        host?.setPaused(true)
+                    }
+                    AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
+                        host?.let { core ->
+                            val current = core.state.value.volume
+                            beforeDucking = beforeDucking ?: current
+                            core.setVolume(current * DUCK_FACTOR)
+                        }
+                    }
+                    AudioManager.AUDIOFOCUS_GAIN -> {
+                        beforeDucking?.let { host?.setVolume(it) }
+                        beforeDucking = null
+                        if (pausedForFocus) {
+                            pausedForFocus = false
+                            host?.setPaused(false)
+                        }
+                    }
                 }
             }.build()
         audioFocus = request
-        audioManager.requestAudioFocus(request)
+        return audioManager.requestAudioFocus(request) == AudioManager.AUDIOFOCUS_REQUEST_GRANTED
     }
 
     private fun updateSession(state: MpvPlaybackState) {
+        refreshSession(state, host?.nowPlaying?.value)
+        if (state.ended) scheduleRetire() else cancelRetire()
+    }
+
+    /**
+     * Retire the session once playback is really over.
+     *
+     * "This file ended" is not "playback is over": autoplay walks to the next
+     * episode, and opening its stream is a network round trip. Retiring inside
+     * that gap leaves the app with no foreground state at all, so the
+     * `startForeground` on the far side is a background start — which API 31+
+     * refuses with `ForegroundServiceStartNotAllowedException`, and this app's
+     * minSdk is 31.
+     */
+    private fun scheduleRetire() {
+        if (retire?.isActive == true) return
+        retire = scope.launch {
+            // The end of file reaches the player and this service from the same
+            // poll, and the player's advance is a recomposition behind. Give it
+            // that long to declare a transition before concluding there is none.
+            delay(TRANSITION_SETTLE_MS)
+            val host = this@PlaybackService.host ?: return@launch
+            withTimeoutOrNull(TRANSITION_GRACE_MS) { host.advancing.first { !it } }
+            if (host.state.value.ended) retirePlayback()
+        }
+    }
+
+    private fun cancelRetire() {
+        retire?.cancel()
+        retire = null
+    }
+
+    private fun refreshSession(state: MpvPlaybackState, playing: NowPlaying?) {
         val status = when {
             state.ended -> PlaybackState.STATE_STOPPED
             state.paused -> PlaybackState.STATE_PAUSED
             else -> PlaybackState.STATE_PLAYING
         }
+        var actions = PlaybackState.ACTION_PLAY or PlaybackState.ACTION_PAUSE or
+            PlaybackState.ACTION_PLAY_PAUSE or PlaybackState.ACTION_SEEK_TO or PlaybackState.ACTION_STOP
+        if (playing?.hasNext == true) actions = actions or PlaybackState.ACTION_SKIP_TO_NEXT
+        if (playing?.hasPrevious == true) actions = actions or PlaybackState.ACTION_SKIP_TO_PREVIOUS
         mediaSession.setPlaybackState(
             PlaybackState.Builder()
-                .setActions(PlaybackState.ACTION_PLAY or PlaybackState.ACTION_PAUSE or PlaybackState.ACTION_SEEK_TO or PlaybackState.ACTION_STOP)
+                .setActions(actions)
                 .setState(status, (state.position * 1_000).toLong(), if (state.paused) 0f else 1f)
                 .build(),
         )
-        mediaSession.setMetadata(
-            MediaMetadata.Builder().putLong(MediaMetadata.METADATA_KEY_DURATION, (state.duration * 1_000).toLong()).build(),
+        mediaSession.setMetadata(metadata(state, playing))
+        val shape = NotificationShape(
+            paused = state.paused,
+            media = playing?.media,
+            title = playing?.title,
+            subtitle = playing?.show,
+            hasPrevious = playing?.hasPrevious == true,
+            hasNext = playing?.hasNext == true,
+            hasArtwork = artwork != null,
         )
-        if (state.ended && foregroundPlayback) {
-            host.releaseEndedStream()
-            retirePlayback()
-            return
-        }
-        if (foregroundPlayback && notifiedPaused != state.paused) {
-            notifiedPaused = state.paused
-            getSystemService(NotificationManager::class.java).notify(NOTIFICATION_ID, notification(state.paused))
+        if (foregroundPlayback && notified != shape) {
+            notified = shape
+            getSystemService(NotificationManager::class.java)
+                .notify(NOTIFICATION_ID, notification(state, playing))
         }
     }
 
+    /**
+     * What the shade, the lock screen and Android Auto read.
+     *
+     * The episode is the title and the show is the artist, which is the mapping
+     * every media surface already lays out well: one prominent line, one
+     * secondary, and the poster behind both.
+     */
+    private fun metadata(state: MpvPlaybackState, playing: NowPlaying?): MediaMetadata =
+        MediaMetadata.Builder()
+            .putString(MediaMetadata.METADATA_KEY_TITLE, playing?.title ?: "proton-stream")
+            .putString(MediaMetadata.METADATA_KEY_DISPLAY_TITLE, playing?.title ?: "proton-stream")
+            .apply {
+                playing?.show?.let {
+                    putString(MediaMetadata.METADATA_KEY_ARTIST, it)
+                    putString(MediaMetadata.METADATA_KEY_ALBUM, it)
+                    putString(MediaMetadata.METADATA_KEY_DISPLAY_SUBTITLE, it)
+                }
+                playing?.detail?.let {
+                    putString(MediaMetadata.METADATA_KEY_DISPLAY_DESCRIPTION, it)
+                }
+                artwork?.second?.let {
+                    putBitmap(MediaMetadata.METADATA_KEY_ALBUM_ART, it)
+                    putBitmap(MediaMetadata.METADATA_KEY_ART, it)
+                    putBitmap(MediaMetadata.METADATA_KEY_DISPLAY_ICON, it)
+                }
+            }
+            .putLong(MediaMetadata.METADATA_KEY_DURATION, (state.duration * 1_000).toLong())
+            .build()
+
     private fun retirePlayback() {
+        cancelRetire()
         if (!sessionPlayback && !foregroundPlayback) return
         sessionPlayback = false
-        notifiedPaused = null
+        notified = null
+        artwork = null
         mediaSession.isActive = false
         audioFocus?.let(audioManager::abandonAudioFocusRequest)
         audioFocus = null
@@ -135,40 +334,98 @@ class PlaybackService : Service() {
         stopSelf()
     }
 
-    private fun notification(paused: Boolean): Notification {
-        val open = PendingIntent.getActivity(
-            this, 0, Intent(this, MainActivity::class.java), PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
-        )
-        val toggleAction = if (paused) ACTION_PLAY else ACTION_PAUSE
-        val toggle = PendingIntent.getService(
-            this, 1, Intent(this, PlaybackService::class.java).setAction(toggleAction), PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
-        )
-        val stop = PendingIntent.getService(
-            this, 2, Intent(this, PlaybackService::class.java).setAction(ACTION_STOP), PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
-        )
+    private fun openActivity(): PendingIntent = PendingIntent.getActivity(
+        this,
+        0,
+        Intent(this, MainActivity::class.java),
+        PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+    )
+
+    private fun command(requestCode: Int, action: String): PendingIntent = PendingIntent.getService(
+        this,
+        requestCode,
+        Intent(this, PlaybackService::class.java).setAction(action),
+        PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+    )
+
+    private fun action(icon: Int, label: String, requestCode: Int, name: String): Notification.Action =
+        Notification.Action.Builder(Icon.createWithResource(this, icon), label, command(requestCode, name)).build()
+
+    private fun notification(state: MpvPlaybackState, playing: NowPlaying?): Notification {
+        val paused = state.paused
+        val actions = buildList {
+            if (playing?.hasPrevious == true) {
+                add(action(android.R.drawable.ic_media_previous, "Previous", 3, ACTION_PREVIOUS))
+            }
+            add(
+                if (paused) action(android.R.drawable.ic_media_play, "Play", 1, ACTION_PLAY)
+                else action(android.R.drawable.ic_media_pause, "Pause", 1, ACTION_PAUSE),
+            )
+            if (playing?.hasNext == true) {
+                add(action(android.R.drawable.ic_media_next, "Next", 4, ACTION_NEXT))
+            }
+            add(action(android.R.drawable.ic_menu_close_clear_cancel, "Stop", 2, ACTION_STOP))
+        }
+        val style = Notification.MediaStyle()
+            .setMediaSession(mediaSession.sessionToken)
+            // The compact view holds three: the transport as it exists for this
+            // episode, so a first episode does not show a dead Previous.
+            .setShowActionsInCompactView(*IntArray(minOf(3, actions.size)) { it })
         return Notification.Builder(this, CHANNEL_ID)
-            .setSmallIcon(android.R.drawable.ic_media_play)
-            .setContentTitle("proton-stream")
-            .setContentText(if (paused) "Playback paused" else "Playing")
-            .setContentIntent(open)
+            .setSmallIcon(R.drawable.ic_notification_stream)
+            .setContentTitle(playing?.title ?: "proton-stream")
+            .setContentText(playing?.show ?: playing?.detail ?: if (paused) "Paused" else "Playing")
+            .apply {
+                playing?.takeIf { it.show != null }?.detail?.let { setSubText(it) }
+                artwork?.second?.let { setLargeIcon(it) }
+            }
+            .setColor(ACCENT)
+            .setColorized(true)
+            .setContentIntent(openActivity())
+            .setDeleteIntent(command(2, ACTION_STOP))
+            .setVisibility(Notification.VISIBILITY_PUBLIC)
             .setOngoing(!paused)
-            .addAction(Notification.Action.Builder(null, if (paused) "Play" else "Pause", toggle).build())
-            .addAction(Notification.Action.Builder(null, "Stop", stop).build())
-            .setStyle(Notification.MediaStyle().setMediaSession(mediaSession.sessionToken).setShowActionsInCompactView(0, 1))
+            .apply { actions.forEach { addAction(it) } }
+            .setStyle(style)
             .build()
     }
 
     private fun createChannel() {
         getSystemService(NotificationManager::class.java).createNotificationChannel(
-            NotificationChannel(CHANNEL_ID, "Playback", NotificationManager.IMPORTANCE_LOW),
+            NotificationChannel(CHANNEL_ID, "Playback", NotificationManager.IMPORTANCE_LOW).apply {
+                description = "Transport controls for the episode being played."
+                setShowBadge(false)
+            },
         )
     }
 
+    /** The inputs the posted notification is built from, and nothing else. */
+    private data class NotificationShape(
+        val paused: Boolean,
+        val media: String?,
+        val title: String?,
+        val subtitle: String?,
+        val hasPrevious: Boolean,
+        val hasNext: Boolean,
+        val hasArtwork: Boolean,
+    )
+
     companion object {
         private const val CHANNEL_ID = "playback"
         private const val NOTIFICATION_ID = 47
+        /** How long a player gets to declare that it is changing episodes. */
+        private const val TRANSITION_SETTLE_MS = 1_000L
+        /** And how long that transition may then take before it is abandoned. */
+        private const val TRANSITION_GRACE_MS = 30_000L
+        /** How far the volume drops for a navigation prompt or a notification. */
+        private const val DUCK_FACTOR = 0.3
+
+        /** Catppuccin Mocha mauve, the accent the app is themed with. */
+        private const val ACCENT = 0xFFCBA6F7.toInt()
         private const val ACTION_PLAY = "io.narl.protonstream.PLAY"
         private const val ACTION_PAUSE = "io.narl.protonstream.PAUSE"
+        private const val ACTION_PREVIOUS = "io.narl.protonstream.PREVIOUS"
+        private const val ACTION_NEXT = "io.narl.protonstream.NEXT"
         private const val ACTION_STOP = "io.narl.protonstream.STOP"
     }
 }

android/app/src/main/java/io/narl/protonstream/playback/PlayerScreen.kt

@@ -0,0 +1,984 @@
+package io.narl.protonstream.playback
+
+import android.app.Activity
+import android.content.pm.ActivityInfo
+import android.view.SurfaceHolder
+import android.view.SurfaceView
+import android.view.WindowManager
+import androidx.activity.compose.BackHandler
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.heightIn
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.windowInsetsPadding
+import androidx.compose.foundation.layout.WindowInsets
+import androidx.compose.foundation.layout.safeDrawing
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.automirrored.filled.Toc
+import androidx.compose.material.icons.automirrored.filled.VolumeOff
+import androidx.compose.material.icons.automirrored.filled.VolumeUp
+import androidx.compose.material.icons.filled.Audiotrack
+import androidx.compose.material.icons.filled.Close
+import androidx.compose.material.icons.filled.Speed
+import androidx.compose.material.icons.filled.Forward30
+import androidx.compose.material.icons.filled.Fullscreen
+import androidx.compose.material.icons.filled.FullscreenExit
+import androidx.compose.material.icons.filled.Pause
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material.icons.filled.Replay10
+import androidx.compose.material.icons.filled.SkipNext
+import androidx.compose.material.icons.filled.SkipPrevious
+import androidx.compose.material.icons.filled.Subtitles
+import androidx.compose.material3.AlertDialog
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Slider
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.geometry.Size
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.platform.LocalWindowInfo
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.viewinterop.AndroidView
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsCompat
+import androidx.core.view.WindowInsetsControllerCompat
+import io.narl.protonstream.native.NativeRuntime
+import io.narl.protonstream.ui.theme.AccentButton
+import io.narl.protonstream.ui.theme.AccentTrack
+import io.narl.protonstream.ui.theme.EdgedButton
+import io.narl.protonstream.ui.theme.QuietButton
+import io.narl.protonstream.ui.theme.TonalButton
+import io.narl.protonstream.ui.thumbnailSource
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import uniffi.pstr_android.ChapterEntry
+import uniffi.pstr_android.EpisodeRecord
+import uniffi.pstr_android.TitleRecord
+import uniffi.pstr_android.TrackPreferencesRecord
+import uniffi.pstr_android.skipOffer
+import kotlin.math.roundToInt
+
+/** How long the controls stay up after a tap. */
+private const val CONTROLS_SECONDS = 4L
+
+/** How long the "up next" card counts down before it loads the next episode. */
+private const val UP_NEXT_SECONDS = 10
+
+/** Past this much of an episode it counts as watched. */
+private const val WATCHED_FRACTION = 0.9
+
+/** The loudest this app plays. Matches `pstr_core::prefs`, which stores it. */
+private const val MAX_VOLUME = 100f
+
+/**
+ * The narrowest layout the in-app volume slider is worth the room it costs.
+ *
+ * Below it — a phone held upright — the transport row is already five controls
+ * wide, and the device's own volume keys are the better answer.
+ */
+private val VOLUME_SLIDER_MIN_WIDTH = 600.dp
+
+/**
+ * The player, as its own screen on the activity's own window.
+ *
+ * Not a dialog: a dialog window has its own insets, cannot be told to draw into
+ * the display cutout, and hands Picture-in-Picture the wrong window. Owning the
+ * activity window is what makes "fullscreen" mean the whole panel, notch
+ * included.
+ *
+ * [episodes] is the title's episodes in display order and [index] the one that is
+ * open, which is what previous/next and autoplay walk. The index is hoisted so
+ * that it survives process recreation with the rest of the navigation state —
+ * this screen is destroyed and rebuilt by a dark-mode toggle like any other.
+ *
+ * In [inPictureInPicture] the window is a thumbnail with the system's own
+ * controls over it, so this screen draws the picture and nothing else.
+ */
+@Composable
+fun PlayerScreen(
+    title: TitleRecord,
+    episodes: List<EpisodeRecord>,
+    index: Int,
+    host: LibmpvHost?,
+    inPictureInPicture: Boolean,
+    minimized: Boolean,
+    onIndexChange: (Int) -> Unit,
+    onSaveProgress: (EpisodeRecord, Double, Double, Boolean) -> Unit,
+    onMinimize: () -> Unit,
+    onClose: () -> Unit,
+) {
+    val context = LocalContext.current
+    val activity = context as? Activity
+    val titleKey = title.key
+    val episode = episodes.getOrNull(index)
+
+    // Minimised, this screen keeps the stream and the effects that own it, and
+    // draws nothing: no surface — mpv plays on without one, exactly as it does
+    // while the app is in the background — no immersive window, and no back
+    // handler, because back belongs to the page the viewer went to.
+    if (!minimized) {
+        ImmersiveWindow(activity)
+        // Back leaves the video rather than ending it. Stopping is the mini
+        // transport's ✕, which is the one place it is unambiguous.
+        BackHandler(onBack = onMinimize)
+    }
+
+    // The transport reads state only this host publishes, so the interface
+    // alone is not enough to draw a player.
+    val nativeHost = host as? NativeMpvHost
+    if (nativeHost == null || episode == null) {
+        if (minimized) return
+        Box(Modifier.fillMaxSize().background(Color.Black), contentAlignment = Alignment.Center) {
+            Text(
+                if (nativeHost == null) "Playback is unavailable: this build does not include libmpv."
+                else "This title has no episode to play.",
+                color = Color.White,
+            )
+        }
+        return
+    }
+
+    val key = mediaKey(episode)
+    val session = remember(key) { RustStreamSession(episode) }
+    var playbackError by remember(key) { mutableStateOf<String?>(null) }
+
+    LaunchedEffect(session, host) {
+        runCatching {
+            val startup = withContext(Dispatchers.IO) {
+                session.open()
+                val engine = NativeRuntime.engine()
+                // A choice made on this title wins; without one, the choice the
+                // viewer made anywhere else does. Both are the desktop client's
+                // fallback chain, and it is what makes "Japanese with English
+                // subtitles" a thing you say once rather than once per show.
+                val show = engine.titleTrackPreferences(titleKey)
+                val global = engine.playbackPrefs()
+                val watch = engine.watchState(episode.shareId, episode.linkId)
+                Startup(
+                    nativeHandle = session.nativeHandle(),
+                    size = session.size(),
+                    // A finished episode restarts rather than resuming three
+                    // seconds from its own credits.
+                    startPosition = watch?.takeUnless { it.watched }?.positionSecs ?: 0.0,
+                    audioLanguage = show?.audioLanguage ?: global.audioLanguage,
+                    subtitleLanguage = show?.subtitleLanguage ?: global.subtitleLanguage,
+                    subtitles = show?.subtitles ?: global.subtitles,
+                    volume = global.volume,
+                    muted = global.muted,
+                    speed = global.speed,
+                )
+            }
+            nativeHost.play(
+                key, startup.nativeHandle, startup.size, startup.startPosition,
+                startup.audioLanguage, startup.subtitleLanguage, startup.subtitles,
+            )
+            // After the load, because mpv keeps none of the three across one.
+            nativeHost.setVolume(startup.volume)
+            nativeHost.setMuted(startup.muted)
+            nativeHost.setSpeed(startup.speed)
+            session.transferToPlayer()
+        }.onFailure { playbackError = it.message ?: "Playback failed" }
+    }
+
+    // Per episode: the stream Rust holds open. The surface is the screen's, not
+    // this episode's, so detaching it belongs to the effect below and not here.
+    DisposableEffect(session) { onDispose { session.close(nativeHost) } }
+    DisposableEffect(nativeHost) { onDispose { nativeHost.detachSurface() } }
+
+    val state by nativeHost.state.collectAsState()
+    val chapters by nativeHost.chapters.collectAsState()
+    val tracks by nativeHost.tracks.collectAsState()
+    // Read once: a preference the viewer changes mid-episode applies to the
+    // next one, and re-reading the store per frame would not.
+    var autoSkip by remember { mutableStateOf(false) }
+    var autoplay by remember { mutableStateOf(true) }
+    LaunchedEffect(Unit) {
+        runCatching { withContext(Dispatchers.IO) { NativeRuntime.engine().playbackPrefs() } }
+            .onSuccess { autoSkip = it.autoSkip; autoplay = it.autoplayNext }
+    }
+
+    // Resume position, written only from readings that carry this episode's
+    // name: one host serves every episode, and an unattributed reading is the
+    // previous one's clock.
+    fun save() {
+        val current = nativeHost.state.value
+        if (current.media == key && current.duration > 0.0) {
+            onSaveProgress(
+                episode,
+                current.position.coerceIn(0.0, current.duration),
+                current.duration,
+                // Watched means played to the end. An episode that was stopped,
+                // or that mpv could not play at all, also "ended" — recording
+                // either as watched retires an episode nobody saw.
+                current.endReason == EndReason.Eof ||
+                    current.position >= current.duration * WATCHED_FRACTION,
+            )
+        }
+    }
+    LaunchedEffect(key) {
+        while (true) {
+            delay(5_000)
+            save()
+        }
+    }
+    DisposableEffect(key) { onDispose { save() } }
+
+    val next = episodes.getOrNull(index + 1)
+    // Both walks tell the host they are one, so the foreground service holds
+    // through the gap where nothing is loaded — see NativeMpvHost.advancing.
+    fun advance() {
+        save()
+        next?.let { nativeHost.beginTransition(); onIndexChange(index + 1) }
+    }
+    fun retreat() {
+        if (index == 0) return
+        save()
+        nativeHost.beginTransition()
+        onIndexChange(index - 1)
+    }
+
+    // What the media notification, the lock screen and Picture-in-Picture show.
+    // None of them can reach this composition, and all three have to name the
+    // episode rather than the app.
+    LaunchedEffect(key, index, episodes.size, title.key) {
+        nativeHost.publish(
+            NowPlaying(
+                media = key,
+                title = episode.label,
+                show = title.canonicalName ?: title.name,
+                detail = episode.detail,
+                artworkUrl = title.posterUrl ?: title.backdropUrl,
+                artworkFile = episode.thumbnailSource,
+                hasPrevious = index > 0,
+                hasNext = next != null,
+            ),
+        )
+    }
+    // Those same surfaces walk the playlist through here, because this is where
+    // the open episode lives. Both callbacks run on the main thread.
+    DisposableEffect(nativeHost, index, episodes.size) {
+        nativeHost.onSkipNext = { advance() }
+        nativeHost.onSkipPrevious = { retreat() }
+        onDispose {
+            nativeHost.onSkipNext = null
+            nativeHost.onSkipPrevious = null
+        }
+    }
+
+    // Autoplay fires on a clean end of file only, and only for this episode's
+    // own reading — never on a failure, and never on the outgoing file's.
+    LaunchedEffect(state.endReason, state.media) {
+        if (state.endReason == EndReason.Eof && state.media == key && autoplay && next != null) advance()
+    }
+    // A file mpv could not play ends like any other. Saying so is the whole
+    // difference between a broken episode and an app that silently skipped one.
+    LaunchedEffect(state.endReason, state.media) {
+        if (state.endReason == EndReason.Failed && state.media == key) {
+            playbackError = "This episode could not be played."
+        }
+    }
+    // What mpv itself complained about, which the play call never sees: by the
+    // time a header turns out to be unreadable it has long since returned.
+    val problem by nativeHost.problem.collectAsState()
+    LaunchedEffect(problem) { problem?.let { playbackError = it } }
+
+    val offer = remember(chapters, key, (state.position * 4).roundToInt()) {
+        runCatching { skipOffer(chapters, state.position) }.getOrNull()
+    }
+    // Auto-skip is offered once per chapter: seeking back into an opening on
+    // purpose must not be undone by the setting that skipped it.
+    val skipped = remember(key) { mutableSetOf<Long>() }
+    LaunchedEffect(offer?.target) {
+        val target = offer?.target ?: return@LaunchedEffect
+        val chapter = chapters.entries.lastOrNull { state.position + 0.001 >= it.start } ?: return@LaunchedEffect
+        if (autoSkip && !state.paused && skipped.add(chapter.index)) nativeHost.seek(target)
+    }
+
+    var landscapeLocked by remember { mutableStateOf(false) }
+    var showControls by remember { mutableStateOf(true) }
+    LaunchedEffect(showControls, state.paused) {
+        if (showControls && !state.paused) {
+            delay(CONTROLS_SECONDS * 1_000)
+            showControls = false
+        }
+    }
+    // Everything this screen draws over the picture is sized for a phone panel
+    // and unreadable in a thumbnail, and Android supplies its own transport
+    // there. Leaving PiP must find the controls up rather than mid-timeout.
+    val overlays = !inPictureInPicture
+    LaunchedEffect(inPictureInPicture) { if (!inPictureInPicture) showControls = true }
+
+    if (minimized) return
+
+    Box(
+        Modifier
+            .fillMaxSize()
+            .background(Color.Black)
+            .clickable(
+                interactionSource = remember { MutableInteractionSource() },
+                indication = null,
+                enabled = overlays,
+                onClick = { showControls = !showControls },
+            ),
+    ) {
+        AndroidView(
+            modifier = Modifier.fillMaxSize(),
+            factory = { viewContext ->
+                SurfaceView(viewContext).apply {
+                    holder.addCallback(object : SurfaceHolder.Callback {
+                        override fun surfaceCreated(holder: SurfaceHolder) = host.attachSurface(holder.surface)
+                        override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) =
+                            host.attachSurface(holder.surface)
+                        override fun surfaceDestroyed(holder: SurfaceHolder) = host.detachSurface()
+                    })
+                }
+            },
+        )
+
+        AnimatedVisibility(
+            visible = overlays && showControls,
+            modifier = Modifier.align(Alignment.TopStart),
+            enter = fadeIn(),
+            exit = fadeOut(),
+        ) {
+            Row(
+                Modifier
+                    .fillMaxWidth()
+                    .background(MaterialTheme.colorScheme.scrim.copy(alpha = 0.45f))
+                    .windowInsetsPadding(WindowInsets.safeDrawing)
+                    .padding(horizontal = 8.dp, vertical = 4.dp),
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                IconButton(onClick = onMinimize) {
+                    Icon(
+                        Icons.AutoMirrored.Filled.ArrowBack,
+                        contentDescription = "Leave the video",
+                        tint = Color.White,
+                    )
+                }
+                // The episode leads and the show follows it: which episode is
+                // the thing a viewer who has just woken the controls is
+                // checking, and the show is what they already know.
+                Column(Modifier.weight(1f)) {
+                    Text(
+                        episode.label,
+                        color = Color.White,
+                        maxLines = 1,
+                        overflow = TextOverflow.Ellipsis,
+                        style = MaterialTheme.typography.titleMedium,
+                    )
+                    Text(
+                        listOfNotNull(title.canonicalName ?: title.name, episode.detail.takeIf(String::isNotBlank))
+                            .joinToString("  •  "),
+                        color = Color.White.copy(alpha = 0.7f),
+                        maxLines = 1,
+                        overflow = TextOverflow.Ellipsis,
+                        style = MaterialTheme.typography.bodySmall,
+                    )
+                }
+                // Two ways out, because they mean different things: back leaves
+                // the video and keeps the episode playing, this ends it.
+                IconButton(onClick = onClose) {
+                    Icon(Icons.Default.Close, contentDescription = "Stop playback", tint = Color.White)
+                }
+                remaining(state)?.let {
+                    Text(
+                        it,
+                        color = Color.White.copy(alpha = 0.7f),
+                        style = MaterialTheme.typography.labelMedium,
+                        modifier = Modifier.padding(start = 12.dp, end = 4.dp),
+                    )
+                }
+            }
+        }
+
+        AnimatedVisibility(
+            visible = overlays && showControls,
+            modifier = Modifier.align(Alignment.BottomCenter),
+            enter = fadeIn(),
+            exit = fadeOut(),
+        ) {
+            PlayerControls(
+                titleKey = titleKey,
+                host = nativeHost,
+                state = state,
+                chapters = chapters.entries,
+                tracks = tracks,
+                hasPrevious = index > 0,
+                hasNext = next != null,
+                onPrevious = { retreat() },
+                onNext = { advance() },
+                onRotate = { landscapeLocked = activity?.toggleLandscape() ?: false },
+                landscapeLocked = landscapeLocked,
+            )
+        }
+
+        // Drawn whether or not the rest of the controls are up: an opening lasts
+        // ninety seconds, and a button you have to wake with a tap is one nobody
+        // reaches in time.
+        offer?.takeIf { overlays && !autoSkip }?.let { skip ->
+            TonalButton(
+                onClick = { nativeHost.seek(skip.target) },
+                modifier = Modifier
+                    .align(Alignment.BottomEnd)
+                    .windowInsetsPadding(WindowInsets.safeDrawing)
+                    .padding(end = 16.dp, bottom = if (showControls) 132.dp else 24.dp),
+            ) { Text(skip.label) }
+        }
+
+        UpNextCard(
+            next = next,
+            visible = overlays && autoplay && !state.paused &&
+                chapters.creditsStart?.let { state.position >= it } == true,
+            onPlayNow = { advance() },
+            modifier = Modifier
+                .align(Alignment.BottomEnd)
+                .windowInsetsPadding(WindowInsets.safeDrawing)
+                .padding(end = 16.dp, bottom = if (showControls) 132.dp else 24.dp),
+        )
+
+        // Only while nothing else explains the still picture: an error is the
+        // more useful thing to say, and a spinner over it reads as "still
+        // trying".
+        if (state.stalled && playbackError == null) {
+            Column(
+                Modifier
+                    .align(Alignment.Center)
+                    .background(MaterialTheme.colorScheme.surfaceContainerHighest, MaterialTheme.shapes.small)
+                    .padding(20.dp),
+                horizontalAlignment = Alignment.CenterHorizontally,
+            ) {
+                CircularProgressIndicator(
+                    color = MaterialTheme.colorScheme.primary,
+                    modifier = Modifier.size(36.dp),
+                )
+                if (state.buffering) {
+                    Text(
+                        state.cachePercent.takeIf { it > 0.0 }
+                            ?.let { "Buffering… ${it.roundToInt()}%" } ?: "Buffering…",
+                        color = MaterialTheme.colorScheme.onSurface,
+                        style = MaterialTheme.typography.labelMedium,
+                        modifier = Modifier.padding(top = 12.dp),
+                    )
+                }
+            }
+        }
+
+        playbackError?.let { message ->
+            Column(
+                Modifier
+                    .align(Alignment.Center)
+                    .background(MaterialTheme.colorScheme.errorContainer, MaterialTheme.shapes.small)
+                    .padding(16.dp),
+                horizontalAlignment = Alignment.CenterHorizontally,
+            ) {
+                Text(message, color = MaterialTheme.colorScheme.onErrorContainer)
+                // Dismissible, because the message is not always fatal — a
+                // subtitle track that failed to load leaves an episode that
+                // plays perfectly well behind an error that used to be permanent.
+                QuietButton(onClick = { playbackError = null; nativeHost.clearProblem() }) {
+                    Text("Dismiss", color = MaterialTheme.colorScheme.onErrorContainer)
+                }
+            }
+        }
+    }
+}
+
+private data class Startup(
+    val nativeHandle: ULong,
+    val size: ULong,
+    val startPosition: Double,
+    val audioLanguage: String?,
+    val subtitleLanguage: String?,
+    val subtitles: Boolean,
+    val volume: Double,
+    val muted: Boolean,
+    val speed: Double,
+)
+
+/**
+ * Immersive for as long as this screen is up, and only that long.
+ *
+ * Hiding the bars is not enough on its own: without `setDecorFitsSystemWindows`
+ * and a cutout mode the picture stops at the notch and at the gesture bar, which
+ * is the "not really fullscreen" everyone notices.
+ */
+@Composable
+private fun ImmersiveWindow(activity: Activity?) {
+    DisposableEffect(activity) {
+        val window = activity?.window
+        if (window == null) return@DisposableEffect onDispose {}
+        val controller = WindowInsetsControllerCompat(window, window.decorView)
+        val previousCutout = window.attributes.layoutInDisplayCutoutMode
+        WindowCompat.setDecorFitsSystemWindows(window, false)
+        window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+        window.attributes = window.attributes.also {
+            it.layoutInDisplayCutoutMode =
+                WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES
+        }
+        controller.hide(WindowInsetsCompat.Type.systemBars())
+        controller.systemBarsBehavior =
+            WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+        onDispose {
+            controller.show(WindowInsetsCompat.Type.systemBars())
+            window.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+            window.attributes = window.attributes.also { it.layoutInDisplayCutoutMode = previousCutout }
+            activity.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
+        }
+    }
+}
+
+/** Lock to landscape, or hand rotation back to the sensor. Reports which. */
+private fun Activity.toggleLandscape(): Boolean {
+    val lock = requestedOrientation != ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
+    requestedOrientation = if (lock) ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE
+    else ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
+    return lock
+}
+
+/**
+ * Everything the transport offers, in two rows.
+ *
+ * A phone in landscape has one thumb's worth of room, so the second row is
+ * icons: the transport cluster on the left, where a thumb already is, and the
+ * pickers on the right. Only the seek bar gets a full row of its own.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+private fun PlayerControls(
+    titleKey: String,
+    host: NativeMpvHost,
+    state: MpvPlaybackState,
+    chapters: List<ChapterEntry>,
+    tracks: List<MpvTrack>,
+    hasPrevious: Boolean,
+    hasNext: Boolean,
+    onPrevious: () -> Unit,
+    onNext: () -> Unit,
+    onRotate: () -> Unit,
+    landscapeLocked: Boolean,
+) {
+    val scope = rememberCoroutineScope()
+    var choosing by remember { mutableStateOf<String?>(null) }
+    var showChapters by remember { mutableStateOf(false) }
+    var showSpeeds by remember { mutableStateOf(false) }
+    // What the store says, so the dialog opens on the rate that is playing.
+    var speed by remember { mutableStateOf(1.0) }
+    LaunchedEffect(Unit) {
+        runCatching { withContext(Dispatchers.IO) { NativeRuntime.engine().playbackPrefs() } }
+            .onSuccess { speed = it.speed }
+    }
+    val duration = state.duration.toFloat().coerceAtLeast(1f)
+    val density = LocalDensity.current
+    val roomForVolume = with(density) {
+        LocalWindowInfo.current.containerSize.width.toDp() >= VOLUME_SLIDER_MIN_WIDTH
+    }
+
+    Column(
+        Modifier
+            .fillMaxWidth()
+            .background(MaterialTheme.colorScheme.scrim.copy(alpha = 0.68f))
+            .windowInsetsPadding(WindowInsets.safeDrawing)
+            .padding(horizontal = 12.dp, vertical = 4.dp),
+    ) {
+        // Where the thumb is while a finger is on it. A seek per touch-move
+        // aborts every outstanding prefetch, so a one-second drag used to issue
+        // dozens of seeks and throw away every in-flight block — and the thumb
+        // snapped backwards under the finger, because it was drawn from a
+        // position that only updates four times a second.
+        var scrubbing by remember { mutableStateOf<Float?>(null) }
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            Text(
+                formatTime(scrubbing?.toDouble() ?: state.position),
+                color = Color.White,
+                style = MaterialTheme.typography.labelMedium,
+            )
+            Box(Modifier.weight(1f)) {
+                Slider(
+                    value = scrubbing ?: state.position.toFloat().coerceIn(0f, duration),
+                    onValueChange = { scrubbing = it },
+                    onValueChangeFinished = {
+                        scrubbing?.let { host.seek(it.toDouble()) }
+                        scrubbing = null
+                    },
+                    valueRange = 0f..duration,
+                    track = { AccentTrack(it) },
+                )
+                ChapterMarks(chapters, state.duration, Modifier.matchParentSize())
+            }
+            Text(formatTime(state.duration), color = Color.White, style = MaterialTheme.typography.labelMedium)
+        }
+        Row(
+            Modifier.fillMaxWidth(),
+            horizontalArrangement = Arrangement.SpaceBetween,
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                CompactIcon(Icons.Default.SkipPrevious, "Previous episode", enabled = hasPrevious, onClick = onPrevious)
+                CompactIcon(Icons.Default.Replay10, "Back ten seconds") { host.seek(state.position - 10) }
+                IconButton(onClick = { host.setPaused(!state.paused) }) {
+                    Icon(
+                        if (state.paused) Icons.Default.PlayArrow else Icons.Default.Pause,
+                        contentDescription = if (state.paused) "Play" else "Pause",
+                        tint = Color.White,
+                        modifier = Modifier.size(32.dp),
+                    )
+                }
+                CompactIcon(Icons.Default.Forward30, "Forward thirty seconds") { host.seek(state.position + 30) }
+                CompactIcon(Icons.Default.SkipNext, "Next episode", enabled = hasNext, onClick = onNext)
+            }
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                if (chapters.size > 1) {
+                    CompactIcon(Icons.AutoMirrored.Filled.Toc, "Chapters") { showChapters = true }
+                }
+                CompactIcon(Icons.Default.Speed, "Playback speed") { showSpeeds = true }
+                CompactIcon(Icons.Default.Audiotrack, "Audio track") { choosing = "audio" }
+                CompactIcon(Icons.Default.Subtitles, "Subtitles") { choosing = "sub" }
+                CompactIcon(
+                    if (state.muted) Icons.AutoMirrored.Filled.VolumeOff else Icons.AutoMirrored.Filled.VolumeUp,
+                    "Mute",
+                ) {
+                    host.setMuted(!state.muted)
+                    scope.launch(Dispatchers.IO) { rememberVolume(muted = !state.muted) }
+                }
+                // The app's own volume, which is not the device's: a file
+                // mastered quiet is turned up here and stays up for the next
+                // one. Only where there is room for it — a phone in portrait
+                // has the system volume keys and no width to spare.
+                if (roomForVolume) {
+                    var dragging by remember { mutableStateOf<Float?>(null) }
+                    Slider(
+                        value = dragging ?: state.volume.toFloat().coerceIn(0f, MAX_VOLUME),
+                        onValueChange = { dragging = it; host.setVolume(it.toDouble()) },
+                        onValueChangeFinished = {
+                            val chosen = dragging?.toDouble()
+                            dragging = null
+                            chosen?.let { scope.launch(Dispatchers.IO) { rememberVolume(volume = it) } }
+                        },
+                        valueRange = 0f..MAX_VOLUME,
+                        modifier = Modifier.width(96.dp),
+                    )
+                }
+                CompactIcon(
+                    if (landscapeLocked) Icons.Default.FullscreenExit else Icons.Default.Fullscreen,
+                    if (landscapeLocked) "Unlock rotation" else "Lock to landscape",
+                    onClick = onRotate,
+                )
+            }
+        }
+    }
+
+    if (showSpeeds) {
+        SpeedChooser(
+            current = speed,
+            onDismiss = { showSpeeds = false },
+            onSelect = { chosen ->
+                speed = chosen
+                host.setSpeed(chosen)
+                showSpeeds = false
+                scope.launch(Dispatchers.IO) { rememberSpeed(chosen) }
+            },
+        )
+    }
+    if (showChapters) {
+        ChapterChooser(
+            chapters = chapters,
+            position = state.position,
+            onDismiss = { showChapters = false },
+            onSelect = { host.seek(it.start); showChapters = false },
+        )
+    }
+    choosing?.let { type ->
+        TrackChooser(
+            type = type,
+            tracks = tracks.filter { it.type == type },
+            onDismiss = { choosing = null },
+            onSelect = { selected ->
+                host.selectTrack(selected)
+                choosing = null
+                scope.launch(Dispatchers.IO) {
+                    val engine = NativeRuntime.engine()
+                    // No per-title choice yet: start from what plays everywhere
+                    // else, so choosing an audio track does not silently drop
+                    // the subtitle preference this episode started with.
+                    val global = engine.playbackPrefs()
+                    val old = engine.titleTrackPreferences(titleKey) ?: TrackPreferencesRecord(
+                        audioLanguage = global.audioLanguage,
+                        subtitleLanguage = global.subtitleLanguage,
+                        subtitles = global.subtitles,
+                    )
+                    engine.setTitleTrackPreferences(
+                        titleKey,
+                        if (type == "audio") {
+                            old.copy(audioLanguage = selected?.language?.takeIf(String::isNotBlank))
+                        } else {
+                            // Turning subtitles off keeps the language it was
+                            // off *from*, so turning them back on does not have
+                            // to be told the language again — as on desktop.
+                            old.copy(
+                                subtitleLanguage = selected?.language?.takeIf(String::isNotBlank)
+                                    ?: old.subtitleLanguage,
+                                subtitles = selected != null,
+                            )
+                        },
+                    )
+                }
+            },
+        )
+    }
+}
+
+/**
+ * Persist a volume or a mute, leaving whichever was not given as it was.
+ *
+ * Written when the thumb is released rather than while it moves: a drag emits
+ * dozens of values a second and every one of them would be a file rewrite. A
+ * failure is dropped — the volume is already applied, and the cost of not
+ * storing it is that the next launch starts where the last one was stored.
+ */
+private suspend fun rememberVolume(volume: Double? = null, muted: Boolean? = null) {
+    runCatching {
+        val engine = NativeRuntime.engine()
+        val prefs = engine.playbackPrefs()
+        engine.setPlaybackPrefs(prefs.copy(volume = volume ?: prefs.volume, muted = muted ?: prefs.muted))
+    }
+}
+
+/** Persist a playback rate, so the next episode starts at it. */
+private suspend fun rememberSpeed(speed: Double) {
+    runCatching {
+        val engine = NativeRuntime.engine()
+        engine.setPlaybackPrefs(engine.playbackPrefs().copy(speed = speed))
+    }
+}
+
+/**
+ * The rates worth offering.
+ *
+ * A short list rather than a slider: the useful rates are a handful of ratios,
+ * and a slider on a phone lands on 1.07 as often as on 1.0.
+ */
+private val SPEEDS = listOf(0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0)
+
+@Composable
+private fun SpeedChooser(current: Double, onDismiss: () -> Unit, onSelect: (Double) -> Unit) {
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Playback speed") },
+        text = {
+            Column(Modifier.fillMaxWidth()) {
+                SPEEDS.forEach { rate ->
+                    EdgedButton(
+                        onClick = { onSelect(rate) },
+                        modifier = Modifier.fillMaxWidth().padding(vertical = 2.dp),
+                    ) {
+                        Text(
+                            (if (kotlin.math.abs(rate - current) < 0.001) "✓  " else "") +
+                                if (rate == 1.0) "Normal" else "${rate}×",
+                        )
+                    }
+                }
+            }
+        },
+        confirmButton = { AccentButton(onClick = onDismiss) { Text("Close") } },
+    )
+}
+
+/** Where each chapter begins, ticked onto the seek bar. */
+@Composable
+private fun ChapterMarks(chapters: List<ChapterEntry>, duration: Double, modifier: Modifier) {
+    if (chapters.size < 2 || duration <= 0.0) return
+    Canvas(modifier.padding(horizontal = 10.dp)) {
+        val width = 2.dp.toPx()
+        val height = 8.dp.toPx()
+        chapters.drop(1).forEach { chapter ->
+            val fraction = (chapter.start / duration).coerceIn(0.0, 1.0).toFloat()
+            drawRect(
+                color = Color.White.copy(alpha = 0.75f),
+                topLeft = Offset(fraction * size.width - width / 2, (size.height - height) / 2),
+                size = Size(width, height),
+            )
+        }
+    }
+}
+
+@Composable
+private fun ChapterChooser(
+    chapters: List<ChapterEntry>,
+    position: Double,
+    onDismiss: () -> Unit,
+    onSelect: (ChapterEntry) -> Unit,
+) {
+    val current = chapters.indexOfLast { position + 0.001 >= it.start }
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text("Chapters") },
+        text = {
+            LazyColumn(Modifier.fillMaxWidth().heightIn(max = 420.dp)) {
+                items(chapters, key = ChapterEntry::index) { chapter ->
+                    EdgedButton(
+                        onClick = { onSelect(chapter) },
+                        modifier = Modifier.fillMaxWidth().padding(vertical = 2.dp),
+                    ) {
+                        Text(
+                            (if (chapters.getOrNull(current) === chapter) "✓  " else "") +
+                                "${formatTime(chapter.start)}  ${chapter.label}",
+                            maxLines = 1,
+                            overflow = TextOverflow.Ellipsis,
+                        )
+                    }
+                }
+            }
+        },
+        confirmButton = { AccentButton(onClick = onDismiss) { Text("Close") } },
+    )
+}
+
+/**
+ * The countdown into the next episode, shown once the credits run starts.
+ *
+ * "Watch till the end" holds for the rest of the file: someone who wants the
+ * post-credits scene should have to say so once, not once every ten seconds.
+ */
+@Composable
+private fun UpNextCard(
+    next: EpisodeRecord?,
+    visible: Boolean,
+    onPlayNow: () -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    var held by remember(next?.linkId) { mutableStateOf(false) }
+    var remaining by remember(next?.linkId) { mutableStateOf(UP_NEXT_SECONDS) }
+    val upNext = next
+    val showing = visible && upNext != null && !held
+    LaunchedEffect(showing) {
+        if (!showing) return@LaunchedEffect
+        remaining = UP_NEXT_SECONDS
+        while (remaining > 0) {
+            delay(1_000)
+            remaining -= 1
+        }
+        onPlayNow()
+    }
+    // `showing` already implies a non-null episode, and the compiler knows it.
+    if (!showing) return
+    Column(
+        modifier
+            .background(MaterialTheme.colorScheme.surfaceContainerHighest, MaterialTheme.shapes.small)
+            .padding(12.dp),
+    ) {
+        Text(
+            "Up next in ${remaining}s",
+            color = MaterialTheme.colorScheme.onSurfaceVariant,
+            style = MaterialTheme.typography.labelMedium,
+        )
+        Text(
+            upNext.label,
+            color = MaterialTheme.colorScheme.onSurface,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+            style = MaterialTheme.typography.titleSmall,
+        )
+        Row(horizontalArrangement = Arrangement.spacedBy(8.dp), modifier = Modifier.padding(top = 8.dp)) {
+            AccentButton(onClick = onPlayNow) { Text("Play now") }
+            QuietButton(onClick = { held = true }) { Text("Watch till the end") }
+        }
+    }
+}
+
+@Composable
+private fun TrackChooser(
+    type: String,
+    tracks: List<MpvTrack>,
+    onDismiss: () -> Unit,
+    onSelect: (MpvTrack?) -> Unit,
+) {
+    AlertDialog(
+        onDismissRequest = onDismiss,
+        title = { Text(if (type == "audio") "Audio track" else "Subtitle track") },
+        text = {
+            LazyColumn(Modifier.fillMaxWidth().heightIn(max = 420.dp)) {
+                if (type == "sub") {
+                    item {
+                        EdgedButton(onClick = { onSelect(null) }, Modifier.fillMaxWidth()) {
+                            Text(if (tracks.none(MpvTrack::selected)) "✓  Off" else "Off")
+                        }
+                    }
+                }
+                items(tracks, key = MpvTrack::id) { track ->
+                    EdgedButton(onClick = { onSelect(track) }, Modifier.fillMaxWidth()) {
+                        Text(if (track.selected) "✓  ${track.label}" else track.label)
+                    }
+                }
+            }
+        },
+        confirmButton = { AccentButton(onClick = onDismiss) { Text("Close") } },
+    )
+}
+
+@Composable
+private fun CompactIcon(
+    icon: androidx.compose.ui.graphics.vector.ImageVector,
+    description: String,
+    enabled: Boolean = true,
+    onClick: () -> Unit,
+) {
+    IconButton(onClick = onClick, enabled = enabled, modifier = Modifier.size(40.dp)) {
+        Icon(
+            icon,
+            contentDescription = description,
+            tint = if (enabled) Color.White else Color.White.copy(alpha = 0.35f),
+            modifier = Modifier.size(22.dp),
+        )
+    }
+}
+
+private fun ((Double) -> Unit).asFloat(): (Float) -> Unit = { this(it.toDouble()) }
+
+/** How much of the episode is left, or nothing before the duration is known. */
+private fun remaining(state: MpvPlaybackState): String? = (state.duration - state.position)
+    .takeIf { state.duration > 0.0 && it >= 1.0 }
+    ?.let { "${formatTime(it)} left" }
+
+private fun formatTime(seconds: Double): String {
+    val total = seconds.coerceAtLeast(0.0).roundToInt()
+    val hours = total / 3_600
+    return if (hours > 0) "%d:%02d:%02d".format(hours, (total % 3_600) / 60, total % 60)
+    else "%d:%02d".format(total / 60, total % 60)
+}

android/app/src/main/java/io/narl/protonstream/playback/StreamSession.kt

@@ -0,0 +1,102 @@
+package io.narl.protonstream.playback
+
+import android.view.Surface
+import io.narl.protonstream.native.NativeRuntime
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import uniffi.pstr_android.AndroidEngine
+import uniffi.pstr_android.AndroidStream
+import uniffi.pstr_android.EpisodeRecord
+
+/** Exact seekable stream contract a bundled libmpv JNI adapter must consume. */
+class RustStreamSession(
+    private val episode: EpisodeRecord,
+) {
+    private var engine: AndroidEngine? = null
+    private var stream: AndroidStream? = null
+    private var handle: ULong? = null
+    private var streamSize: ULong? = null
+
+    suspend fun open(): RustStreamSession = withContext(Dispatchers.IO) {
+        val openedEngine = NativeRuntime.engine()
+        engine = openedEngine
+        stream = openedEngine.openStream(episode.shareId, episode.volumeId, episode.linkId).also {
+            streamSize = it.size()
+            handle = it.nativeHandle()
+        }
+        this@RustStreamSession
+    }
+
+    fun nativeHandle(): ULong = checkNotNull(handle) { "stream is not published" }
+
+    fun size(): ULong = checkNotNull(streamSize) { "stream is not open" }
+
+    fun releaseNative(host: LibmpvHost) {
+        handle?.let(host::releaseNativeStream)
+        handle = null
+        streamSize = null
+        stream = null
+    }
+
+    /** The native player now owns the published token until stop/end/close. */
+    fun transferToPlayer() {
+        handle = null
+        streamSize = null
+        stream = null
+    }
+
+    /**
+     * Give the episode's stream back to Rust, from a scope of this session's own.
+     *
+     * Deliberately not the caller's: the one moment this has to run is when the
+     * player leaves the composition, which is the same moment a
+     * `rememberCoroutineScope` is cancelled — so a release launched there is
+     * cancelled before it starts, and the stream is held for the life of the
+     * process. Once per episode played, that is every episode.
+     */
+    fun close(host: LibmpvHost) {
+        releaseNative(host)
+        sessions.launch {
+            runCatching { engine?.releaseStream(episode.shareId, episode.volumeId, episode.linkId) }
+            engine = null
+        }
+    }
+}
+
+/**
+ * Where stream teardown runs: process-lifetime, like the engine it releases to,
+ * and never cancelled by a screen going away.
+ */
+private val sessions = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+/** Implement only in the variant that bundles a pinned libmpv native artifact. */
+interface LibmpvHost {
+    fun attachSurface(surface: Surface)
+    fun detachSurface()
+
+    /**
+     * Consumes the opaque handle through pstr_android_stream_{read,size}.
+     *
+     * [media] names the episode being loaded. One host serves every episode in
+     * turn, so its readings have to say which one they describe — see
+     * [MpvPlaybackState.media].
+     */
+    suspend fun play(
+        media: String,
+        nativeHandle: ULong,
+        size: ULong,
+        startPosition: Double = 0.0,
+        audioLanguage: String? = null,
+        subtitleLanguage: String? = null,
+        subtitles: Boolean = true,
+    )
+
+    /** Calls pstr_android_stream_release exactly once for a published handle. */
+    fun releaseNativeStream(nativeHandle: ULong)
+}
+
+/** How an episode is named in watch state, work names and player readings. */
+fun mediaKey(episode: EpisodeRecord) = "${episode.shareId}:${episode.linkId}"

android/app/src/main/java/io/narl/protonstream/settings/SettingsStore.kt

@@ -2,6 +2,13 @@ package io.narl.protonstream.settings
 
 import android.content.Context
 
+/**
+ * The settings that are Android's alone.
+ *
+ * Playback preferences — volume, languages, autoplay, auto-skip — deliberately
+ * do *not* live here: they are `pstr_core::prefs`, reached over the bridge, so
+ * there is one definition of them rather than one per front end.
+ */
 class SettingsStore(context: Context) {
     private val preferences = context.getSharedPreferences(NAME, Context.MODE_PRIVATE)
 

android/app/src/main/java/io/narl/protonstream/ui/AppViewModel.kt

@@ -28,8 +28,11 @@ import io.narl.protonstream.native.NativeRuntime
 import uniffi.pstr_android.ShareRecord
 import uniffi.pstr_android.TitleRecord
 import uniffi.pstr_android.OfflineRecord
+import uniffi.pstr_android.MatchSummary
 import uniffi.pstr_android.MetadataProvider
 import uniffi.pstr_android.MetadataSettingsRecord
+import uniffi.pstr_android.StorageUsageRecord
+import uniffi.pstr_android.EpisodeRecord
 
 data class AppUiState(
     val loading: Boolean = true,
@@ -44,6 +47,7 @@ data class AppUiState(
         language = "en",
         ready = true,
     ),
+    val storage: StorageUsageRecord = StorageUsageRecord(0uL, 0uL, 0uL, 0uL),
     val message: String? = null,
 )
 
@@ -55,6 +59,11 @@ class AppViewModel(context: Context, private val workManager: WorkManager) : Vie
     val state: StateFlow<AppUiState> = mutableState.asStateFlow()
 
     init {
+        if (!NativeRuntime.tlsReady) {
+            mutableState.update {
+                it.copy(message = "Certificate verification is unavailable; Proton requests will fail")
+            }
+        }
         reload()
         viewModelScope.launch {
             searchQuery.debounce(300).distinctUntilChanged().collect { reloadLibrary(it) }
@@ -83,6 +92,43 @@ class AppViewModel(context: Context, private val workManager: WorkManager) : Vie
         }
     }
 
+    /**
+     * Recrawl one share rather than the whole library.
+     *
+     * A viewer who has just added files to one link should not have to pay for
+     * a walk of every other one — and a share whose link has expired makes a
+     * whole-library refresh fail, which used to leave no way to refresh the
+     * shares that still work.
+     */
+    fun refreshShare(id: String) {
+        viewModelScope.launch {
+            mutableState.update { it.copy(refreshing = true, message = null) }
+            runCatching { withContext(Dispatchers.IO) { NativeRuntime.engine().crawl(id) } }
+                .onFailure { error -> mutableState.update { it.copy(message = error.message) } }
+            mutableState.update { it.copy(refreshing = false) }
+            reload()
+        }
+    }
+
+    /**
+     * Run enrichment again.
+     *
+     * With [force] every title is looked up afresh, including ones that already
+     * matched — the way out of a library where a provider's early answers were
+     * wrong, or where a match was made against a provider that has since been
+     * changed.
+     */
+    fun matchTitles(force: Boolean) {
+        viewModelScope.launch {
+            mutableState.update { it.copy(refreshing = true, message = null) }
+            runCatching { withContext(Dispatchers.IO) { NativeRuntime.engine().matchTitles(force) } }
+                .onSuccess { summary -> mutableState.update { it.copy(message = describe(summary)) } }
+                .onFailure { error -> mutableState.update { it.copy(message = error.message) } }
+            mutableState.update { it.copy(refreshing = false) }
+            reload()
+        }
+    }
+
     fun addShare(name: String, url: String, password: String?) {
         viewModelScope.launch {
             runCatching {
@@ -96,6 +142,28 @@ class AppViewModel(context: Context, private val workManager: WorkManager) : Vie
         }
     }
 
+    /**
+     * Re-supply the link behind a share whose stored secret cannot be read.
+     *
+     * The Keystore key is invalidated by a lockscreen change or a device
+     * restore, and after that every open of every share fails — including the
+     * read inside "remove this share", so the obvious way out is closed too.
+     * Re-entering the link rewrites the secret and leaves the catalog and the
+     * offline files alone.
+     */
+    fun repairShare(id: String, url: String, password: String?) {
+        viewModelScope.launch {
+            runCatching {
+                withContext(Dispatchers.IO) {
+                    val engine = NativeRuntime.engine()
+                    engine.repairShare(id, url, password?.takeIf(String::isNotBlank))
+                    engine.crawl(id)
+                }
+            }.onFailure(::reportError)
+            reload()
+        }
+    }
+
     fun removeShare(id: String) {
         viewModelScope.launch {
             runCatching {
@@ -132,8 +200,10 @@ class AppViewModel(context: Context, private val workManager: WorkManager) : Vie
                         engine.setMetadataApiKey(provider, apiKey)
                     }
                     engine.setMetadataSettings(MetadataSettingsRecord(enabled, provider, language, true))
-                    if (enabled) engine.matchTitles(false)
+                    if (enabled) engine.matchTitles(false) else null
                 }
+            }.onSuccess { summary ->
+                summary?.let { mutableState.update { state -> state.copy(message = describe(it)) } }
             }.onFailure(::reportError)
             reload()
         }
@@ -141,6 +211,23 @@ class AppViewModel(context: Context, private val workManager: WorkManager) : Vie
 
     fun reloadAfterMetadataChange() = reload()
 
+    /**
+     * What an enrichment pass did, in one line.
+     *
+     * Failures are reported even when most titles matched: a run that quietly
+     * dropped a third of the library is the case this counting exists for.
+     */
+    private fun describe(summary: MatchSummary): String {
+        if (summary.matched == 0u && summary.unmatched == 0u && summary.failed == 0u) {
+            return "Everything is already matched"
+        }
+        val parts = mutableListOf("${summary.matched} matched")
+        if (summary.unmatched > 0u) parts += "${summary.unmatched} not found"
+        if (summary.episodes > 0u) parts += "${summary.episodes} episodes named"
+        if (summary.failed > 0u) parts += "${summary.failed} failed"
+        return parts.joinToString(", ")
+    }
+
     fun removeOffline(file: OfflineRecord) {
         viewModelScope.launch {
             runCatching {
@@ -170,16 +257,96 @@ class AppViewModel(context: Context, private val workManager: WorkManager) : Vie
         }
     }
 
+    /**
+     * Persist where an episode was left.
+     *
+     * The player calls this while it is still up and once more as it leaves, so
+     * it runs on the ViewModel's scope rather than the screen's — a save issued
+     * on the way out must not be cancelled by the screen going away.
+     */
+    fun saveProgress(episode: EpisodeRecord, position: Double, duration: Double, watched: Boolean) {
+        viewModelScope.launch {
+            runCatching {
+                withContext(Dispatchers.IO) {
+                    NativeRuntime.engine().saveWatchState(
+                        episode.shareId,
+                        episode.linkId,
+                        position.coerceIn(0.0, duration),
+                        duration,
+                        watched,
+                    )
+                }
+            }.onFailure(::reportError)
+        }
+    }
+
+    /**
+     * Mark an episode seen, or unseen, without playing it.
+     *
+     * Unwatching rewinds, matching the desktop client: an episode marked unseen
+     * that kept its position would come straight back as "resume at 19:04",
+     * which is not what the viewer asked for. Marking one seen puts the position
+     * at its duration where one is known, so the progress bar agrees with the
+     * tick.
+     */
+    fun setWatched(episode: EpisodeRecord, watched: Boolean) {
+        viewModelScope.launch {
+            runCatching {
+                withContext(Dispatchers.IO) {
+                    val engine = NativeRuntime.engine()
+                    val duration = engine.watchState(episode.shareId, episode.linkId)?.durationSecs
+                    engine.saveWatchState(
+                        episode.shareId,
+                        episode.linkId,
+                        if (watched) duration ?: 0.0 else 0.0,
+                        duration,
+                        watched,
+                    )
+                }
+            }.onFailure(::reportError)
+            reload()
+        }
+    }
+
+    fun removeAllOffline() {
+        viewModelScope.launch {
+            runCatching {
+                withContext(Dispatchers.IO) {
+                    workManager.cancelAllWorkByTag(DownloadCoordinator.TAG).result.get()
+                    NativeRuntime.engine().removeAllOffline()
+                    DownloadStateStore(appContext).clear()
+                }
+            }.onFailure(::reportError)
+            reload()
+        }
+    }
+
+    fun clearBlockCache() {
+        viewModelScope.launch {
+            runCatching {
+                withContext(Dispatchers.IO) { NativeRuntime.engine().clearBlockCache() }
+            }.onSuccess { reclaimed ->
+                mutableState.update { it.copy(message = "Reclaimed ${formatBytes(reclaimed)} of cache") }
+            }.onFailure(::reportError)
+            reload()
+        }
+    }
+
     private fun reload() {
         viewModelScope.launch {
             runCatching {
                 withContext(Dispatchers.IO) {
                     val engine = NativeRuntime.engine()
+                    // Here rather than inside `library()`, which is read-only
+                    // and cached: a full reload is the one place that has
+                    // already paid for a walk of the offline files.
+                    engine.pruneOfflineFiles()
                     Reloaded(
                         engine.shares(),
                         engine.library(mutableState.value.query.takeIf(String::isNotBlank)),
                         engine.offlineFiles(),
                         engine.metadataSettings(),
+                        engine.storageUsage(),
                     )
                 }
             }.onSuccess { result ->
@@ -189,6 +356,7 @@ class AppViewModel(context: Context, private val workManager: WorkManager) : Vie
                         titles = result.titles,
                         offline = result.offline,
                         metadataSettings = result.metadataSettings,
+                        storage = result.storage,
                     ) }
                 }
                 .onFailure { error ->
@@ -215,6 +383,7 @@ private data class Reloaded(
     val titles: List<TitleRecord>,
     val offline: List<OfflineRecord>,
     val metadataSettings: MetadataSettingsRecord,
+    val storage: StorageUsageRecord,
 )
 
 private fun WorkManager.workInfosByTagFlow(tag: String) = callbackFlow {

android/app/src/main/java/io/narl/protonstream/ui/RemoteArtwork.kt

@@ -1,6 +1,9 @@
 package io.narl.protonstream.ui
 
+import android.content.Context
+import android.graphics.Bitmap
 import android.graphics.BitmapFactory
+import android.util.LruCache
 import androidx.compose.foundation.Image
 import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Box
@@ -19,50 +22,61 @@ import androidx.compose.ui.graphics.ImageBitmap
 import androidx.compose.ui.graphics.asImageBitmap
 import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.platform.LocalContext
+import io.narl.protonstream.native.NativeRuntime
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
+import uniffi.pstr_android.EpisodeRecord
+import uniffi.pstr_android.TitleRecord
 import java.net.HttpURLConnection
 import java.net.URI
 import java.io.ByteArrayOutputStream
+import java.io.File
 import java.io.InputStream
 import java.security.MessageDigest
+import java.util.Collections
 
-/** HTTPS-only artwork loader backed by the app-private cache directory. */
+/**
+ * One file to pull Proton's own thumbnail from when no provider poster exists.
+ *
+ * Proton renders a thumbnail per file, so any episode of a show is a frame of
+ * the right show — the desktop client picks the first for the same reason.
+ */
+data class ThumbnailSource(val shareId: String, val volumeId: String, val linkId: String) {
+    val key: String get() = "$shareId/$linkId"
+}
+
+/**
+ * What the first episode of a title offers as a poster.
+ *
+ * Metadata lookups are off by default, so for a freshly crawled library this is
+ * the only artwork there is.
+ */
+internal val TitleRecord.thumbnailSource: ThumbnailSource?
+    get() = seasons.firstNotNullOfOrNull { season -> season.episodes.firstOrNull() }
+        ?.let { ThumbnailSource(it.shareId, it.volumeId, it.linkId) }
+
+/** What one episode offers as a still. */
+internal val EpisodeRecord.thumbnailSource: ThumbnailSource
+    get() = ThumbnailSource(shareId, volumeId, linkId)
+
+/**
+ * HTTPS-only artwork loader backed by the app-private cache directory.
+ *
+ * [fallback] is used only when there is no provider artwork or it fails to
+ * load, which — with metadata off — is the common case rather than the rare
+ * one.
+ */
 @Composable
-internal fun RemoteArtwork(url: String?, description: String, modifier: Modifier = Modifier) {
+internal fun RemoteArtwork(
+    url: String?,
+    description: String,
+    modifier: Modifier = Modifier,
+    fallback: ThumbnailSource? = null,
+) {
     val context = LocalContext.current
-    var image by remember(url) { mutableStateOf<ImageBitmap?>(null) }
-    LaunchedEffect(url) {
-        image = url?.let { requested ->
-            withContext(Dispatchers.IO) {
-                runCatching {
-                    val uri = URI(requested)
-                    require(uri.scheme.equals("https", ignoreCase = true)) { "Artwork must use HTTPS" }
-                    val directory = context.cacheDir.resolve("metadata-art").apply { mkdirs() }
-                    val digest = MessageDigest.getInstance("SHA-256")
-                        .digest(requested.toByteArray()).joinToString("") { "%02x".format(it) }
-                    val cached = directory.resolve("$digest.img")
-                    val bytes = if (cached.isFile) cached.readBytes() else {
-                        val connection = uri.toURL().openConnection() as HttpURLConnection
-                        connection.connectTimeout = 10_000
-                        connection.readTimeout = 10_000
-                        connection.instanceFollowRedirects = true
-                        val status = connection.responseCode
-                        require(status in 200..299) { "Artwork request failed ($status)" }
-                        require(connection.url.protocol.equals("https", ignoreCase = true)) {
-                            "Artwork redirect must use HTTPS"
-                        }
-                        connection.inputStream.use(::readBounded).also { downloaded ->
-                            require(downloaded.size <= MAX_ART_BYTES) { "Artwork is too large" }
-                            val temporary = directory.resolve("$digest.part")
-                            temporary.writeBytes(downloaded)
-                            check(temporary.renameTo(cached)) { "Unable to cache artwork" }
-                        }
-                    }
-                    BitmapFactory.decodeByteArray(bytes, 0, bytes.size)?.asImageBitmap()
-                }.getOrNull()
-            }
-        }
+    var image by remember(url, fallback) { mutableStateOf<ImageBitmap?>(null) }
+    LaunchedEffect(url, fallback) {
+        image = (loadArtwork(context, url) ?: loadThumbnail(fallback))?.asImageBitmap()
     }
     Box(modifier.background(MaterialTheme.colorScheme.surfaceVariant), contentAlignment = Alignment.Center) {
         image?.let {
@@ -71,7 +85,153 @@ internal fun RemoteArtwork(url: String?, description: String, modifier: Modifier
     }
 }
 
+/**
+ * The same HTTPS-only fetch behind the library grid, reusable off the composition.
+ *
+ * The media notification needs a bitmap rather than an [ImageBitmap], and needs
+ * it from a service with no composition of its own — but it wants exactly this
+ * loader's protocol checks and exactly this disk cache, so the artwork the shade
+ * shows costs no second download.
+ */
+internal suspend fun loadArtwork(context: Context, url: String?): Bitmap? = url?.let { requested ->
+    decoded.get(requested) ?: withContext(Dispatchers.IO) {
+        runCatching {
+            val uri = URI(requested)
+            require(uri.scheme.equals("https", ignoreCase = true)) { "Artwork must use HTTPS" }
+            val directory = context.cacheDir.resolve("metadata-art").apply { mkdirs() }
+            val digest = MessageDigest.getInstance("SHA-256")
+                .digest(requested.toByteArray()).joinToString("") { "%02x".format(it) }
+            val cached = directory.resolve("$digest.img")
+            val fresh = !cached.isFile
+            val bytes = if (fresh) download(uri) else cached.readBytes()
+            val bitmap = requireNotNull(decodeSampled(bytes)) { "Artwork is not a decodable image" }
+            if (fresh) {
+                // Written only once it has decoded. Caching the bytes first is
+                // what turns one hostile poster into a crash on every launch
+                // that survives until app data is cleared.
+                val temporary = directory.resolve("$digest.part")
+                temporary.writeBytes(bytes)
+                check(temporary.renameTo(cached)) { "Unable to cache artwork" }
+                prune(directory)
+            } else {
+                cached.setLastModified(System.currentTimeMillis())
+            }
+            bitmap
+        }.getOrNull()?.also { decoded.put(requested, it) }
+    }
+}
+
+/**
+ * Proton's own thumbnail for one file, decoded.
+ *
+ * The bridge holds the disk cache, so what is worth keeping here is the decoded
+ * bitmap and the *absence* of one: a file with no thumbnail is common, and
+ * without remembering that, every scroll back over the grid pays a round trip
+ * per tile to be told so again. A failed call is not remembered — an unreachable
+ * share or a session that has to be reopened is transient, and the next
+ * composition should try again.
+ */
+internal suspend fun loadThumbnail(source: ThumbnailSource?): Bitmap? {
+    val file = source ?: return null
+    val key = file.key
+    decoded.get(key)?.let { return it }
+    if (key in missing) return null
+    val fetched = withContext(Dispatchers.IO) {
+        runCatching { NativeRuntime.engine().thumbnail(file.shareId, file.volumeId, file.linkId) }
+    }
+    val bytes = fetched.getOrElse { return null }
+    val bitmap = bytes?.let { withContext(Dispatchers.Default) { decodeSampled(it) } }
+    if (bitmap == null) {
+        missing.add(key)
+        return null
+    }
+    decoded.put(key, bitmap)
+    return bitmap
+}
+
+private fun download(uri: URI): ByteArray {
+    val connection = uri.toURL().openConnection() as HttpURLConnection
+    connection.connectTimeout = 10_000
+    connection.readTimeout = 10_000
+    connection.instanceFollowRedirects = true
+    val status = connection.responseCode
+    require(status in 200..299) { "Artwork request failed ($status)" }
+    require(connection.url.protocol.equals("https", ignoreCase = true)) {
+        "Artwork redirect must use HTTPS"
+    }
+    return connection.inputStream.use(::readBounded)
+        .also { require(it.size <= MAX_ART_BYTES) { "Artwork is too large" } }
+}
+
+/**
+ * Decode within a bound the display can actually use.
+ *
+ * [MAX_ART_BYTES] bounds the *compressed* image, which says nothing about what
+ * it costs decoded: a 12 MiB PNG can be 12000×12000, and that is a 576 MB
+ * `ARGB_8888` allocation on a device that will not give it. The bounds pass
+ * costs no allocation and settles a sample size before anything is committed.
+ */
+private fun decodeSampled(bytes: ByteArray): Bitmap? {
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    BitmapFactory.decodeByteArray(bytes, 0, bytes.size, bounds)
+    val longest = maxOf(bounds.outWidth, bounds.outHeight)
+    if (longest <= 0) return null
+    var sample = 1
+    while (longest / sample > MAX_ART_EDGE) sample *= 2
+    return BitmapFactory.decodeByteArray(
+        bytes,
+        0,
+        bytes.size,
+        BitmapFactory.Options().apply { inSampleSize = sample },
+    )
+}
+
+/**
+ * Hold the cache directory under [MAX_ART_CACHE_BYTES], oldest first.
+ *
+ * `cacheDir` is reclaimable by the system, but only under storage pressure and
+ * only wholesale — a poster cache that grows with every title ever browsed is
+ * still the app's own doing.
+ */
+private fun prune(directory: File) {
+    val files = directory.listFiles()?.sortedBy(File::lastModified) ?: return
+    var total = files.sumOf(File::length)
+    for (file in files) {
+        if (total <= MAX_ART_CACHE_BYTES) return
+        total -= file.length()
+        file.delete()
+    }
+}
+
+/**
+ * Files known to have no Proton thumbnail, so the answer is paid for once.
+ *
+ * Deliberately not persisted: a re-upload can add one, and the cost of being
+ * wrong for a session is a placeholder that a restart clears.
+ */
+private val missing: MutableSet<String> = Collections.synchronizedSet(mutableSetOf())
+
+/**
+ * Decoded posters, so scrolling the grid re-reads neither disk nor decoder.
+ *
+ * Keyed by artwork URL or by `share/link` for a Proton thumbnail; the two
+ * cannot collide, since one is always an `https:` URL.
+ *
+ * `remember(url)` is per-composition, and a `LazyVerticalGrid` drops and
+ * recreates items as they leave the viewport — without this, every scroll back
+ * is a full-resolution decode per item.
+ */
+private val decoded = object : LruCache<String, Bitmap>(
+    (Runtime.getRuntime().maxMemory() / 8).coerceIn(4L * 1024 * 1024, 32L * 1024 * 1024).toInt(),
+) {
+    override fun sizeOf(key: String, value: Bitmap): Int = value.byteCount
+}
+
 private const val MAX_ART_BYTES = 12 * 1024 * 1024
+private const val MAX_ART_CACHE_BYTES = 48L * 1024 * 1024
+
+/** Longest edge worth decoding: a poster on a phone, or a notification icon. */
+private const val MAX_ART_EDGE = 1_024
 
 /** Reads at most [MAX_ART_BYTES] plus one byte without requiring API 33's readNBytes. */
 private fun readBounded(input: InputStream): ByteArray {

android/app/src/main/java/io/narl/protonstream/ui/theme/Accent.kt

@@ -0,0 +1,223 @@
+package io.narl.protonstream.ui.theme
+
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.RowScope
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.FilledTonalButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.NavigationBarItemDefaults
+import androidx.compose.material3.NavigationDrawerItemDefaults
+import androidx.compose.material3.NavigationRailItemDefaults
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteDefaults
+import androidx.compose.material3.adaptive.navigationsuite.NavigationSuiteItemColors
+import androidx.compose.material3.SliderState
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.geometry.CornerRadius
+import androidx.compose.ui.geometry.Size
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.SolidColor
+import androidx.compose.ui.unit.dp
+
+/**
+ * The accent, as a gradient when there is one to draw.
+ *
+ * The desktop paints the accent as a two-hue ramp on everything that is a
+ * control — the seek bar, the primary buttons, the tile progress bar — and the
+ * viewer's "paint the accent as a gradient" toggle is what turns it off. That
+ * toggle was already stored, already offered on this screen, and drawn nowhere
+ * on Android, so the same stored setting meant two different things depending
+ * on which client read it.
+ *
+ * Nothing here reads the toggle. It does not need to: when gradients are off,
+ * `Palette::resolve` sets `accent_alt` equal to `accent`, so the ramp collapses
+ * to a flat fill on its own. `primary` and `secondary` are those two colours —
+ * see [schemeOf] — which is why this asks Material for them rather than
+ * reaching past it for the palette.
+ */
+@Composable
+internal fun accentBrush(): Brush {
+    val scheme = MaterialTheme.colorScheme
+    return remember(scheme.primary, scheme.secondary) {
+        Brush.horizontalGradient(listOf(scheme.primary, scheme.secondary))
+    }
+}
+
+/**
+ * The primary button: the accent ramp, at the shared corner radius.
+ *
+ * Material's filled button has its own shape token (`CornerFull`) that does not
+ * read `MaterialTheme.shapes`, so the radius has to be handed to it — which is
+ * the whole reason the plain buttons below exist as well. They add nothing but
+ * that.
+ */
+@Composable
+internal fun AccentButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+    content: @Composable RowScope.() -> Unit,
+) {
+    val shape = MaterialTheme.shapes.small
+    Button(
+        onClick = onClick,
+        // Only while it is live: a disabled button keeps Material's flat
+        // disabled container, because a greyed control that still wears the
+        // one strong colour in the window reads as pressable.
+        modifier = if (enabled) modifier.background(accentBrush(), shape) else modifier,
+        enabled = enabled,
+        shape = shape,
+        colors = ButtonDefaults.buttonColors(containerColor = Color.Transparent),
+        content = content,
+    )
+}
+
+@Composable
+internal fun TonalButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+    content: @Composable RowScope.() -> Unit,
+) = FilledTonalButton(
+    onClick = onClick,
+    modifier = modifier,
+    enabled = enabled,
+    shape = MaterialTheme.shapes.small,
+    content = content,
+)
+
+@Composable
+internal fun EdgedButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+    content: @Composable RowScope.() -> Unit,
+) = OutlinedButton(
+    onClick = onClick,
+    modifier = modifier,
+    enabled = enabled,
+    shape = MaterialTheme.shapes.small,
+    content = content,
+)
+
+@Composable
+internal fun QuietButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+    content: @Composable RowScope.() -> Unit,
+) = TextButton(
+    onClick = onClick,
+    modifier = modifier,
+    enabled = enabled,
+    shape = MaterialTheme.shapes.small,
+    content = content,
+)
+
+/**
+ * How far along something is, drawn in the accent.
+ *
+ * Hand-drawn rather than `LinearProgressIndicator` because that one takes a
+ * `Color` and not a `Brush`, and because Material 1.4 draws a gap and a stop
+ * indicator either side of the bar — detail at a size where the desktop draws a
+ * plain bar. [fill] is a parameter for the one bar that is deliberately not the
+ * accent: a download in flight sits directly under the watch-progress bar of
+ * the same row, and two ramps in the same colour stacked two pixels apart say
+ * nothing.
+ */
+@Composable
+internal fun AccentProgress(
+    progress: () -> Float,
+    modifier: Modifier = Modifier,
+    fill: Brush? = null,
+) {
+    val brush = fill ?: accentBrush()
+    val track = MaterialTheme.colorScheme.surfaceContainerHighest
+    Canvas(modifier.fillMaxWidth().height(PROGRESS_HEIGHT.dp)) {
+        val radius = CornerRadius(size.height / 2)
+        drawRoundRect(color = track, cornerRadius = radius)
+        val done = size.width * progress().coerceIn(0f, 1f)
+        // Below one bar's width there is nothing to round, and a rounded rect
+        // narrower than its own corners draws as a wrong-looking pill.
+        if (done >= size.height) {
+            drawRoundRect(brush = brush, size = Size(done, size.height), cornerRadius = radius)
+        }
+    }
+}
+
+/**
+ * The seek bar's track, in the accent ramp.
+ *
+ * Passed to `Slider`'s `track` slot, so the thumb, the gestures and the
+ * accessibility semantics stay Material's — this replaces the two rectangles it
+ * would have drawn and nothing else.
+ *
+ * The spent side is the accent and the rest is white at a third: the seek bar
+ * is the one accent surface that sits over arbitrary film footage, where a
+ * palette colour for the *unplayed* remainder would be a coloured line over a
+ * picture rather than the absence of one.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+internal fun AccentTrack(state: SliderState, modifier: Modifier = Modifier) {
+    val brush = accentBrush()
+    Canvas(modifier.fillMaxWidth().height(TRACK_HEIGHT.dp)) {
+        val radius = CornerRadius(size.height / 2)
+        drawRoundRect(color = Color.White.copy(alpha = 0.30f), cornerRadius = radius)
+        val done = size.width * state.coercedValueAsFraction
+        if (done >= size.height) {
+            drawRoundRect(brush = brush, size = Size(done, size.height), cornerRadius = radius)
+        }
+    }
+}
+
+/**
+ * The navigation pill, in the accent.
+ *
+ * Solid rather than a ramp, and this is the one place the two clients cannot
+ * agree exactly: `NavigationSuiteScaffold` takes the indicator as a `Color`,
+ * with no slot to draw into, so a gradient here would mean reimplementing the
+ * bar. The accent itself is still the right answer — the desktop's rule is that
+ * the accent marks the thing you are on — and it is nearer to that than
+ * `secondaryContainer`, which is the accent taken most of the way back to the
+ * page.
+ */
+@Composable
+internal fun accentNavigationColors(): NavigationSuiteItemColors {
+    val scheme = MaterialTheme.colorScheme
+    return NavigationSuiteDefaults.itemColors(
+        navigationBarItemColors = NavigationBarItemDefaults.colors(
+            selectedIconColor = scheme.onPrimary,
+            selectedTextColor = scheme.onSurface,
+            indicatorColor = scheme.primary,
+        ),
+        navigationRailItemColors = NavigationRailItemDefaults.colors(
+            selectedIconColor = scheme.onPrimary,
+            selectedTextColor = scheme.onSurface,
+            indicatorColor = scheme.primary,
+        ),
+        navigationDrawerItemColors = NavigationDrawerItemDefaults.colors(
+            selectedContainerColor = scheme.primary,
+            selectedIconColor = scheme.onPrimary,
+            selectedTextColor = scheme.onPrimary,
+        ),
+    )
+}
+
+/** A solid fill, for the callers of [AccentProgress] that want one colour. */
+internal fun solid(color: Color): Brush = SolidColor(color)
+
+/** Thin enough to sit under a row without becoming part of it. */
+private const val PROGRESS_HEIGHT = 4f
+
+/** The seek bar is dragged with a finger, so it is the thicker of the two. */
+private const val TRACK_HEIGHT = 6f

android/app/src/main/java/io/narl/protonstream/ui/theme/Shape.kt

@@ -0,0 +1,36 @@
+package io.narl.protonstream.ui.theme
+
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Shapes
+import androidx.compose.ui.unit.dp
+
+/**
+ * One corner radius, which is the desktop client's corner radius.
+ *
+ * `pstr-app` rounds every surface it paints to 8 — cards, buttons, the tab
+ * pill, the progress bars — and only a badge over artwork is tighter, at 4.
+ * Material's default ramp runs 4 / 8 / 12 / 16 / 28, so a stock Compose screen
+ * puts a 28dp bottom sheet next to a 12dp card next to a fully-round button,
+ * and none of those is the shape the other client draws.
+ *
+ * Flat rather than a ramp, therefore, with the two ends kept for the two cases
+ * where a single radius is wrong: `extraSmall` for something small enough that
+ * 8 would eat it, and `extraLarge` for a sheet whose corners meet the edge of
+ * the screen and need to read as a lifted sheet rather than a seam.
+ */
+internal val ProtonShapes = Shapes(
+    extraSmall = RoundedCornerShape(CORNER_TIGHT.dp),
+    small = RoundedCornerShape(CORNER.dp),
+    medium = RoundedCornerShape(CORNER.dp),
+    large = RoundedCornerShape(CORNER.dp),
+    extraLarge = RoundedCornerShape(CORNER_SHEET.dp),
+)
+
+/** The radius `pstr-app` draws everything at. */
+internal const val CORNER = 8f
+
+/** A badge over artwork — `ui/mod.rs` is the other place this number lives. */
+internal const val CORNER_TIGHT = 4f
+
+/** A bottom sheet, which has no desktop counterpart. */
+internal const val CORNER_SHEET = 16f

android/app/src/main/java/io/narl/protonstream/ui/theme/Theme.kt

@@ -1,24 +1,216 @@
 package io.narl.protonstream.ui.theme
 
+import androidx.compose.material3.ColorScheme
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.lightColorScheme
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
 import androidx.compose.ui.graphics.Color
+import io.narl.protonstream.native.NativeRuntime
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.withContext
+import uniffi.pstr_android.PaletteRecord
 
-private val ProtonColors = darkColorScheme(
-    primary = Color(0xFFCBA6F7),
-    onPrimary = Color(0xFF1E1E2E),
-    secondary = Color(0xFFF5C2E7),
-    background = Color(0xFF1E1E2E),
-    surface = Color(0xFF181825),
-    surfaceVariant = Color(0xFF313244),
-    onBackground = Color(0xFFCDD6F4),
-    onSurface = Color(0xFFCDD6F4),
-    outline = Color(0xFF6C7086),
-    error = Color(0xFFF38BA8),
-)
+/**
+ * The palette in force, shared across every composition.
+ *
+ * The choice is stored by Rust and resolved by Rust — the same flavours, the
+ * same accent pairings and the same contrast rule the desktop client uses — so
+ * what lives here is only the resolved answer and a way to replace it when the
+ * viewer picks something else.
+ */
+object AppearanceState {
+    private val current = MutableStateFlow<PaletteRecord?>(null)
+    val palette: StateFlow<PaletteRecord?> = current.asStateFlow()
+
+    /**
+     * The palette read before the first frame, from
+     * [io.narl.protonstream.native.NativeRuntime.storedPalette].
+     *
+     * Separate from [load] because it runs on the main thread during
+     * `onCreate`: it is the only read that is early enough to decide what the
+     * first composition is painted in, and it is cheap enough to be allowed
+     * there.
+     */
+    fun seed(palette: PaletteRecord) {
+        current.value = palette
+    }
+
+    /**
+     * Read the stored choice through the engine. Safe to call repeatedly; the
+     * last read wins.
+     *
+     * A no-op once [seed] has run — it resolves the same file through the same
+     * Rust, so the only thing a second read can do is build the engine earlier
+     * than the first screen needed it.
+     */
+    suspend fun load() {
+        if (current.value != null) return
+        runCatching { withContext(Dispatchers.IO) { NativeRuntime.engine().palette() } }
+            .onSuccess { current.value = it }
+    }
+
+    /** Repaint immediately, before the write that stores the choice lands. */
+    fun apply(palette: PaletteRecord) {
+        current.value = palette
+    }
+}
 
 @Composable
 fun ProtonStreamTheme(content: @Composable () -> Unit) {
-    MaterialTheme(colorScheme = ProtonColors, content = content)
+    val palette by AppearanceState.palette.collectAsState()
+    // Before the first read, and if it fails, the palette this app shipped
+    // with — a theme file that cannot be read must never be a reason the
+    // library does not open.
+    LaunchedEffect(Unit) { AppearanceState.load() }
+    MaterialTheme(
+        colorScheme = schemeOf(palette ?: ProtonFallback),
+        // The other two thirds of what the clients share. Colour was already
+        // one resolved answer for both; type and shape were Material's defaults
+        // here and named constants there, which is most of why the two read as
+        // different apps even where the colours agreed.
+        typography = ProtonTypography,
+        shapes = ProtonShapes,
+        content = content,
+    )
 }
+
+/**
+ * One resolved palette as Material's roles — **all** of them.
+ *
+ * Every role Material names has to be answered here, because a role left out
+ * does not fall back to something neutral: it keeps the value
+ * `darkColorScheme()` / `lightColorScheme()` gave it, which is Material's own
+ * baseline purple-and-grey and belongs to no flavour this app ships.
+ *
+ * That is not hypothetical. `surfaceContainerHighest` is what `Card` fills with
+ * (`FilledCardTokens.ContainerColor`), and while it was unmapped every tile in
+ * the library grid, every episode row, every share and every download was drawn
+ * in baseline neutral on top of a flavoured page. `inverseSurface` is the
+ * snackbar — the app's only error channel — and `scrim` is the dim behind every
+ * dialog.
+ *
+ * Material names more roles than a palette has colours, so several are answered
+ * by the same one, and two (`elevated`, `dangerDim`) are derived in Rust so the
+ * blend behind them is the shared one. `SchemeRolesTest` asserts that nothing
+ * here is left at its baseline.
+ */
+internal fun schemeOf(palette: PaletteRecord): ColorScheme {
+    val base = if (palette.light) lightColorScheme() else darkColorScheme()
+    return base.copy(
+        primary = color(palette.accent),
+        onPrimary = color(palette.onAccent),
+        primaryContainer = color(palette.accentDim),
+        onPrimaryContainer = color(palette.text),
+        // Readable *on* `inverseSurface`, which is the ink colour: `accentDim`
+        // is the accent taken towards the page, so it inverts with the rest.
+        inversePrimary = color(palette.accentDim),
+        secondary = color(palette.accentAlt),
+        onSecondary = color(palette.onAccent),
+        // The accent taken back towards the page, not the card's hover shade.
+        // `secondaryContainer` is what fills every tonal button and the
+        // navigation bar's selected pill, and `cardHover` sits one step off
+        // `card` — which on a dark flavour made all of them dark grey shapes on
+        // a dark grey row, readable as text but not as controls.
+        secondaryContainer = color(palette.accentDim),
+        onSecondaryContainer = color(palette.text),
+        // The palette has two hues, not three. Tertiary takes the second one —
+        // the gradient partner — rather than inventing a third that no flavour
+        // chose.
+        tertiary = color(palette.accentAlt),
+        onTertiary = color(palette.onAccent),
+        tertiaryContainer = color(palette.accentDim),
+        onTertiaryContainer = color(palette.text),
+        background = color(palette.background),
+        onBackground = color(palette.text),
+        surface = color(palette.surface),
+        onSurface = color(palette.text),
+        surfaceVariant = color(palette.card),
+        onSurfaceVariant = color(palette.muted),
+        // No elevation tint. Material tints a raised surface with `primary`,
+        // and the desktop draws no such tint at all — its rule is that the
+        // accent is the only strong colour in the window and everything wearing
+        // it is something to click. A card that is faintly accent-coloured
+        // because it happens to be raised breaks that.
+        surfaceTint = Color.Transparent,
+        // Genuinely inverted, both ways round: on a dark flavour this is a pale
+        // snackbar with dark ink, on Latte a dark one with pale ink.
+        inverseSurface = color(palette.text),
+        inverseOnSurface = color(palette.background),
+        error = color(palette.danger),
+        onError = color(palette.background),
+        errorContainer = color(palette.dangerDim),
+        onErrorContainer = color(palette.text),
+        // Swapped from what was here before, to match what Material draws with
+        // each: `outline` is a border meant to be seen (an outlined button,
+        // a swatch that is not selected), `outlineVariant` is a divider meant
+        // to be barely there. `border` is the fainter of the two.
+        outline = color(palette.muted),
+        outlineVariant = color(palette.border),
+        // Black in both of Material's own schemes, and for the same reason: a
+        // scrim is not a colour, it is an absence of light.
+        scrim = Color.Black,
+        surfaceBright = color(palette.elevated),
+        surfaceDim = color(palette.background),
+        // The containment ladder, in the order the palette already runs: the
+        // deepest colour in the flavour at the bottom, `elevated` — one step
+        // past the card's hover shade — at the top.
+        surfaceContainerLowest = color(palette.sunken),
+        surfaceContainerLow = color(palette.surface),
+        surfaceContainer = color(palette.card),
+        surfaceContainerHigh = color(palette.cardHover),
+        surfaceContainerHighest = color(palette.elevated),
+        // The fixed roles are Material's "the same in light and dark", which a
+        // per-flavour palette has no equivalent of. They take the accent pair
+        // rather than a baseline hue, so a component that reaches for one still
+        // lands inside the flavour.
+        primaryFixed = color(palette.accentDim),
+        primaryFixedDim = color(palette.accent),
+        onPrimaryFixed = color(palette.text),
+        onPrimaryFixedVariant = color(palette.muted),
+        secondaryFixed = color(palette.accentDim),
+        secondaryFixedDim = color(palette.accentAlt),
+        onSecondaryFixed = color(palette.text),
+        onSecondaryFixedVariant = color(palette.muted),
+        tertiaryFixed = color(palette.accentDim),
+        tertiaryFixedDim = color(palette.accentAlt),
+        onTertiaryFixed = color(palette.text),
+        onTertiaryFixedVariant = color(palette.muted),
+    )
+}
+
+/** A packed `0xAARRGGBB` from the bridge, as Compose wants it. */
+private fun color(argb: UInt) = Color(argb.toInt())
+
+/**
+ * The shipped default, spelled out for the case where Rust cannot be asked.
+ *
+ * A `PaletteRecord` rather than a `ColorScheme`, so that it goes through
+ * [schemeOf] like any other palette and inherits every mapping above — a
+ * fallback that answered only ten roles would be the same bug in a smaller
+ * place. The values are `pstr_core::appearance::Palette::PROTON`.
+ */
+internal val ProtonFallback = PaletteRecord(
+    background = 0xFF0E0E12u,
+    surface = 0xFF17171Du,
+    sunken = 0xFF0A0A0Du,
+    card = 0xFF1E1E26u,
+    cardHover = 0xFF2A2A35u,
+    border = 0xFF262630u,
+    text = 0xFFEAEAF0u,
+    muted = 0xFF8E8E9Cu,
+    accent = 0xFF7D4DFFu,
+    accentAlt = 0xFF3F6FE0u,
+    accentDim = 0xFF5333ADu,
+    onAccent = 0xFFEAEAF0u,
+    danger = 0xFFE05561u,
+    elevated = 0xFF333340u,
+    dangerDim = 0xFF7F2F37u,
+    light = false,
+)

android/app/src/main/java/io/narl/protonstream/ui/theme/Type.kt

@@ -0,0 +1,75 @@
+package io.narl.protonstream.ui.theme
+
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.sp
+
+/**
+ * The type ramp, which is the desktop client's type ramp.
+ *
+ * `pstr_app::theme::Role` names nine sizes and the desktop asks for a role
+ * rather than a number at every call site. Material names fifteen styles, so
+ * several of them land on the same rung — that is the point. The two clients
+ * were built to share one palette; sharing one scale is the other half of why
+ * they should read as one app.
+ *
+ * The rungs, largest first: 26 / 20 / 18 / 17 / 15 / 14 / 13 / 12 / 11.
+ *
+ * Where a role maps is decided by what actually draws with it here, not by
+ * Material's own sizes — Material's `displayLarge` is 57sp, which is a size for
+ * a phone's lock screen and not for anything in a library grid. `bodyLarge` is
+ * what an unstyled `Text` gets, so it takes the desktop's body rung and the two
+ * smaller body styles step down from there.
+ *
+ * [TypeRampTest] pins every one of these against the Rust ramp.
+ */
+internal val ProtonTypography = Typography(
+    displayLarge = role(DISPLAY, FontWeight.SemiBold),
+    displayMedium = role(DISPLAY, FontWeight.SemiBold),
+    displaySmall = role(TITLE, FontWeight.SemiBold),
+    // The name of the title you opened — the desktop's display line.
+    headlineLarge = role(DISPLAY, FontWeight.SemiBold),
+    headlineMedium = role(DISPLAY, FontWeight.SemiBold),
+    // A dialog's heading — `AlertDialog` titles draw with this one.
+    headlineSmall = role(HEADING, FontWeight.SemiBold),
+    // A page heading: "Offline downloads", "Settings".
+    titleLarge = role(TITLE, FontWeight.SemiBold),
+    // A run of content under a heading: "Continue watching", "Playback".
+    titleMedium = role(SECTION, FontWeight.Medium),
+    // A row that groups the rows under it — a season header.
+    titleSmall = role(SUBHEAD, FontWeight.Medium),
+    bodyLarge = role(BODY, FontWeight.Normal),
+    bodyMedium = role(LABEL, FontWeight.Normal),
+    // Context rather than content: counts, sizes, the note under a field.
+    bodySmall = role(CAPTION, FontWeight.Normal),
+    // The text on a button.
+    labelLarge = role(LABEL, FontWeight.Medium),
+    labelMedium = role(CAPTION, FontWeight.Medium),
+    // The smallest thing that stays legible.
+    labelSmall = role(MICRO, FontWeight.Medium),
+)
+
+internal const val DISPLAY = 26f
+internal const val TITLE = 20f
+internal const val HEADING = 18f
+internal const val SECTION = 17f
+internal const val SUBHEAD = 15f
+internal const val BODY = 14f
+internal const val LABEL = 13f
+internal const val CAPTION = 12f
+internal const val MICRO = 11f
+
+/**
+ * One rung as a `TextStyle`.
+ *
+ * Line height is derived rather than named per style: a ramp whose leading was
+ * chosen nine separate times is the same problem the sizes had. 1.35 is loose
+ * enough for the two-line title names in the grid and tight enough that a
+ * label on a control does not float.
+ */
+private fun role(size: Float, weight: FontWeight) = TextStyle(
+    fontSize = size.sp,
+    lineHeight = (size * 1.35f).sp,
+    fontWeight = weight,
+)

android/app/src/main/res/drawable/ic_notification_stream.xml

@@ -0,0 +1,13 @@
+<!--
+  The status-bar glyph. Android tints small icons to a single colour and drops
+  everything that is not opaque, so this is the launcher mark reduced to one
+  white silhouette rather than the two-tone drawable.
+-->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp" android:height="24dp"
+    android:viewportWidth="24" android:viewportHeight="24">
+    <path
+        android:fillColor="#FFFFFFFF"
+        android:fillType="evenOdd"
+        android:pathData="M4,4h16v16h-16zM10,8.5l5.5,3.5 -5.5,3.5z" />
+</vector>

android/app/src/main/res/values/colors.xml

@@ -0,0 +1,9 @@
+<resources>
+    <!--
+      `pstr_core::appearance::Palette::PROTON.background` — the shipped default,
+      and the only colour in this file. It is what the window is painted before
+      the stored palette has been read; from then on
+      MainActivity.dressWindow overrides it with the flavour in force.
+    -->
+    <color name="window_background">#0E0E12</color>
+</resources>

android/app/src/main/res/values/themes.xml

@@ -1,8 +1,23 @@
 <resources>
+    <!--
+      The window before Compose owns it.
+
+      Everything about the *look* is decided by the stored palette and applied
+      in MainActivity.dressWindow: the background colour here is only the one
+      the shipped default resolves to, so that a first-ever launch — before
+      there is a theme file to read — starts on the right colour rather than on
+      the platform's white. The bar polarity is likewise set from the palette;
+      what is left here is the dark reading, which is right for four of the five
+      flavours and is corrected in the same frame for the fifth.
+
+      A hex literal from one specific flavour used to live here, and it was the
+      reason every cold start flashed Catppuccin Mocha's base regardless of what
+      the viewer had chosen.
+    -->
     <style name="Theme.ProtonStream" parent="android:style/Theme.Material.NoActionBar">
         <item name="android:fontFamily">sans</item>
         <item name="android:windowLightStatusBar">false</item>
         <item name="android:windowLightNavigationBar">false</item>
-        <item name="android:windowBackground">#1E1E2E</item>
+        <item name="android:windowBackground">@color/window_background</item>
     </style>
 </resources>

android/app/src/test/java/io/narl/protonstream/download/DownloadStateStoreTest.kt

@@ -0,0 +1,155 @@
+package io.narl.protonstream.download
+
+import android.content.Context
+import androidx.test.core.app.ApplicationProvider
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+@RunWith(RobolectricTestRunner::class)
+class DownloadStateStoreTest {
+    private lateinit var context: Context
+    private lateinit var store: DownloadStateStore
+
+    @Before
+    fun setUp() {
+        context = ApplicationProvider.getApplicationContext()
+        context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE).edit().clear().commit()
+        store = DownloadStateStore(context)
+    }
+
+    private fun record(
+        shareId: String = "share-1",
+        linkId: String = "link-1",
+        label: String = "S01E01.mkv",
+        status: String = RetainedDownload.STATUS_RUNNING,
+        error: String? = null,
+    ) = RetainedDownload(
+        shareId = shareId,
+        volumeId = "volume-1",
+        linkId = linkId,
+        label = label,
+        downloaded = 4L * 1024 * 1024,
+        total = 761L * 1024 * 1024,
+        status = status,
+        error = error,
+    )
+
+    @Test
+    fun `a record survives a round trip unchanged`() {
+        val original = record()
+        store.put(original)
+        assertEquals(original, store.get("share-1", "link-1"))
+    }
+
+    @Test
+    fun `an absent record reads as null rather than a default`() {
+        assertNull(store.get("share-1", "link-1"))
+    }
+
+    @Test
+    fun `an error message round trips and a null one stays null`() {
+        store.put(record(error = "no space left on device"))
+        assertEquals("no space left on device", store.get("share-1", "link-1")?.error)
+
+        store.put(record(error = null))
+        assertNull(store.get("share-1", "link-1")?.error)
+    }
+
+    /**
+     * `encode` writes `error` through `JSONObject.put`, which *removes* the key
+     * when the value is null. `decode` then reads `optString`, which answers ""
+     * rather than null. The blank check is the only thing standing between a
+     * cleared error and a download that renders as permanently failed.
+     */
+    @Test
+    fun `a blank error is not read as a failure message`() {
+        writeRaw(
+            "share-1",
+            "link-1",
+            baseJson().put("error", ""),
+        )
+        assertNull(store.get("share-1", "link-1")?.error)
+    }
+
+    /** Rows written before `label` existed fall back to the link id. */
+    @Test
+    fun `a record with no label is captioned with its link id`() {
+        writeRaw("share-1", "link-1", baseJson().apply { remove("label") })
+        assertEquals("link-1", store.get("share-1", "link-1")?.label)
+    }
+
+    @Test
+    fun `a corrupt row is skipped rather than failing the whole list`() {
+        store.put(record(linkId = "link-1", label = "good.mkv"))
+        context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+            .edit()
+            .putString("share-1\u001flink-broken", "{ not json")
+            .commit()
+
+        val records = store.records()
+        assertEquals(1, records.size)
+        assertEquals("good.mkv", records.first().label)
+    }
+
+    @Test
+    fun `records are ordered by label without regard to case`() {
+        store.put(record(linkId = "a", label = "beta.mkv"))
+        store.put(record(linkId = "b", label = "Alpha.mkv"))
+        assertEquals(listOf("Alpha.mkv", "beta.mkv"), store.records().map { it.label })
+    }
+
+    @Test
+    fun `removing one share leaves the others alone`() {
+        store.put(record(shareId = "share-1", linkId = "a"))
+        store.put(record(shareId = "share-2", linkId = "b"))
+
+        store.removeShare("share-1")
+
+        assertEquals(listOf("share-2"), store.records().map { it.shareId })
+    }
+
+    @Test
+    fun `clear forgets everything`() {
+        store.put(record(linkId = "a"))
+        store.put(record(linkId = "b"))
+        store.clear()
+        assertTrue(store.records().isEmpty())
+    }
+
+    /**
+     * The key is what `DownloadCoordinator` and `OfflineDownloadWorker` agree on
+     * across processes; two shares may legitimately hold the same link id.
+     */
+    @Test
+    fun `the key separates share from link so ids cannot run together`() {
+        store.put(record(shareId = "a", linkId = "b-c"))
+        store.put(record(shareId = "a-b", linkId = "c"))
+        assertEquals(2, store.records().size)
+    }
+
+    private fun baseJson() = JSONObject()
+        .put("share", "share-1")
+        .put("volume", "volume-1")
+        .put("link", "link-1")
+        .put("label", "S01E01.mkv")
+        .put("downloaded", 0)
+        .put("total", 0)
+        .put("status", RetainedDownload.STATUS_QUEUED)
+
+    private fun writeRaw(shareId: String, linkId: String, json: JSONObject) {
+        context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+            .edit()
+            .putString("$shareId\u001f$linkId", json.toString())
+            .commit()
+    }
+
+    private companion object {
+        const val PREFERENCES = "offline_download_state"
+    }
+}

android/app/src/test/java/io/narl/protonstream/ui/theme/SchemeRolesTest.kt

@@ -0,0 +1,129 @@
+package io.narl.protonstream.ui.theme
+
+import androidx.compose.material3.ColorScheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.ui.graphics.Color
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import uniffi.pstr_android.PaletteRecord
+
+/**
+ * That every Material colour role is answered by the palette.
+ *
+ * Material names roughly fifty roles and a `ColorScheme` is built by copying a
+ * baseline, so a role nobody names keeps Material's own purple-and-grey —
+ * silently, and only where that particular role happens to be drawn. That is
+ * how `surfaceContainerHighest` went unnoticed: nothing referred to it by name,
+ * but it is what `Card` fills with, so every tile, episode row, share and
+ * download in the app was baseline neutral on a flavoured page.
+ *
+ * The check is reflective rather than a list, because a list is exactly as
+ * incomplete as the mapping it was written from — and because Material adds
+ * roles between versions, and a role added tomorrow should fail this the day
+ * the dependency moves.
+ */
+class SchemeRolesTest {
+    /**
+     * A palette whose every colour is distinct and none of which Material would
+     * ever produce, so that "this role came from the palette" is decidable by
+     * looking at the value.
+     */
+    private fun sentinels(light: Boolean) = PaletteRecord(
+        background = 0xFF010203u,
+        surface = 0xFF040506u,
+        sunken = 0xFF070809u,
+        card = 0xFF0A0B0Cu,
+        cardHover = 0xFF0D0E0Fu,
+        border = 0xFF101112u,
+        text = 0xFF131415u,
+        muted = 0xFF161718u,
+        accent = 0xFF191A1Bu,
+        accentAlt = 0xFF1C1D1Eu,
+        accentDim = 0xFF1F2021u,
+        onAccent = 0xFF222324u,
+        danger = 0xFF252627u,
+        elevated = 0xFF28292Au,
+        dangerDim = 0xFF2B2C2Du,
+        light = light,
+    )
+
+    /** Every role on a `ColorScheme`, read by name, whatever the version names. */
+    private fun roles(scheme: ColorScheme): Map<String, Color> =
+        ColorScheme::class.java.declaredMethods
+            .filter { it.name.startsWith("get") && it.parameterCount == 0 && it.returnType == Long::class.java }
+            .associate { method ->
+                method.isAccessible = true
+                // Kotlin mangles the getter of a value-class property:
+                // `getPrimary-0d7_KjU`. The property is what the name says up
+                // to the dash.
+                method.name.removePrefix("get").substringBefore('-') to
+                    Color((method.invoke(scheme) as Long).toULong())
+            }
+
+    @Test
+    fun `every role is answered by the palette`() {
+        for (light in listOf(false, true)) {
+            val palette = sentinels(light)
+            val allowed = buildSet {
+                addAll(
+                    listOf(
+                        palette.background, palette.surface, palette.sunken, palette.card,
+                        palette.cardHover, palette.border, palette.text, palette.muted,
+                        palette.accent, palette.accentAlt, palette.accentDim, palette.onAccent,
+                        palette.danger, palette.elevated, palette.dangerDim,
+                    ).map { Color(it.toInt()) },
+                )
+                // The two roles that are deliberately not a palette colour: no
+                // elevation tint at all, and a scrim that is an absence of
+                // light rather than a hue.
+                add(Color.Transparent)
+                add(Color.Black)
+            }
+
+            val leaked = roles(schemeOf(palette)).filterValues { it !in allowed }
+            assertTrue(
+                "light=$light: ${leaked.keys.sorted()} still carry Material's baseline",
+                leaked.isEmpty(),
+            )
+        }
+    }
+
+    /**
+     * The count is asserted too. A reflective sweep that found no roles at all
+     * would pass the check above for the wrong reason.
+     */
+    @Test
+    fun `the sweep sees the whole scheme`() {
+        val count = roles(darkColorScheme()).size
+        assertTrue("only $count roles found; the reflective sweep is not working", count >= 40)
+        assertEquals(count, roles(lightColorScheme()).size)
+    }
+
+    /**
+     * Which baseline was copied stops being observable once every role is
+     * mapped — and that is the point.
+     *
+     * `light` still decides plenty, but it decides it in Rust, where it picks
+     * the flavour's colours. By the time a palette reaches Kotlin the
+     * light-or-dark question is already answered *inside* the colours, so two
+     * palettes that differ only in the flag have to produce the same scheme. If
+     * they ever stop doing so, something is reading `light` here rather than
+     * reading the colours.
+     */
+    @Test
+    fun `the baseline no longer shows through`() {
+        assertEquals(roles(schemeOf(sentinels(false))), roles(schemeOf(sentinels(true))))
+        assertEquals(Color.Transparent, schemeOf(sentinels(false)).surfaceTint)
+    }
+
+    /** The fallback goes through the same mapping as any other palette. */
+    @Test
+    fun `the shipped fallback is fully mapped too`() {
+        val scheme = schemeOf(ProtonFallback)
+        assertEquals(Color(ProtonFallback.elevated.toInt()), scheme.surfaceContainerHighest)
+        assertEquals(Color(ProtonFallback.card.toInt()), scheme.surfaceContainer)
+        assertEquals(Color(ProtonFallback.dangerDim.toInt()), scheme.errorContainer)
+    }
+}

android/app/src/test/java/io/narl/protonstream/ui/theme/TypeRampTest.kt

@@ -0,0 +1,109 @@
+package io.narl.protonstream.ui.theme
+
+import androidx.compose.material3.Typography
+import androidx.compose.ui.text.TextStyle
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * That the type ramp is the ramp, and the corner radius is the radius.
+ *
+ * The two clients share a palette because one Rust function resolves it for
+ * both. Type and shape have no such bridge — they are named in
+ * `pstr_app::theme::Role` and copied here — so what stops them drifting is this
+ * test and the numbers in it. Change the Rust ramp and this fails; that is the
+ * point of it.
+ *
+ * Every style is named rather than checked against a set, because "some rung"
+ * is not the property that matters: `bodyMedium`'s Material default is 14sp,
+ * which is a rung, so a `bodyMedium` nobody mapped would pass a looser check
+ * while sitting one step off where it belongs.
+ */
+class TypeRampTest {
+    /** `Role::size()`, in the order `theme.rs` declares it. */
+    private val ramp = listOf(26f, 20f, 18f, 17f, 15f, 14f, 13f, 12f, 11f)
+
+    private val expected = mapOf(
+        "displayLarge" to 26f,
+        "displayMedium" to 26f,
+        "displaySmall" to 20f,
+        "headlineLarge" to 26f,
+        "headlineMedium" to 26f,
+        "headlineSmall" to 18f,
+        "titleLarge" to 20f,
+        "titleMedium" to 17f,
+        "titleSmall" to 15f,
+        "bodyLarge" to 14f,
+        "bodyMedium" to 13f,
+        "bodySmall" to 12f,
+        "labelLarge" to 13f,
+        "labelMedium" to 12f,
+        "labelSmall" to 11f,
+    )
+
+    @Test
+    fun `every text style sits on the shared ramp`() {
+        expected.forEach { (name, size) ->
+            assertEquals(name, size, styles().getValue(name).fontSize.value, 0.001f)
+        }
+    }
+
+    /**
+     * Material adds type styles between versions, and one added tomorrow would
+     * arrive at whatever size Material chose for it. The list above is only as
+     * complete as the day it was written unless something says so.
+     */
+    @Test
+    fun `no text style is left at Material's own size`() {
+        assertEquals(expected.keys, styles().keys)
+    }
+
+    /**
+     * Leading is derived from the size, so the only thing worth asserting is
+     * that it *was* derived — a style that kept Material's line height carries
+     * a number with no relation to its own size.
+     */
+    @Test
+    fun `line height follows the size it belongs to`() {
+        styles().forEach { (name, style) ->
+            assertEquals(name, style.fontSize.value * 1.35f, style.lineHeight.value, 0.01f)
+        }
+    }
+
+    @Test
+    fun `the ramp has no rung the styles never reach`() {
+        val drawn = styles().values.map { it.fontSize.value }.toSet()
+        ramp.forEach { rung -> assertTrue("$rung is named but never drawn", rung in drawn) }
+    }
+
+    @Test
+    fun `every surface is drawn at the desktop's radius`() {
+        listOf(ProtonShapes.small, ProtonShapes.medium, ProtonShapes.large).forEach { shape ->
+            // `CornerSize` resolves against a size and a density, and neither is
+            // available to a unit test; `toString` is the only handle on the
+            // value that does not need a composition.
+            assertTrue("$shape is not radius $CORNER", shape.toString().contains("$CORNER"))
+        }
+    }
+
+    /**
+     * Every text style a caller can set, read by name, whatever the version
+     * names.
+     *
+     * Material 1.4 carries a second, `Emphasized` copy of all fifteen for its
+     * expressive components. Those are `internal` — the constructor takes them
+     * but Kotlin will not let this module pass them — so they keep Material's
+     * own sizes and nothing here can do anything about it. Their getters are
+     * name-mangled with `$material3`, which is how they are told apart from a
+     * public style that genuinely went unmapped.
+     */
+    private fun styles(): Map<String, TextStyle> = Typography::class.java.declaredMethods
+        .filter { it.parameterCount == 0 && it.returnType == TextStyle::class.java }
+        .filterNot { '$' in it.name }
+        .associate { method ->
+            method.isAccessible = true
+            method.name.removePrefix("get").replaceFirstChar(Char::lowercaseChar) to
+                method.invoke(ProtonTypography) as TextStyle
+        }
+}

android/app/src/test/resources/robolectric.properties

@@ -0,0 +1,11 @@
+# Robolectric ships no Android image for API 36 yet, and defaults to the app's
+# targetSdk, so host tests would fail to start. 34 is the newest it has and is
+# well above minSdk 31; anything whose behaviour actually turns on the API level
+# belongs in androidTest, on a real device, not here.
+sdk=34
+
+# ProtonStreamApplication.onCreate() calls System.loadLibrary("pstr_android"),
+# which has no host build. Host tests get a plain Application; everything that
+# needs the bridge is an instrumentation test by construction — see
+# androidTest/.../UniFfiBoundaryTest.
+application=android.app.Application

android/gradle/libs.versions.toml

@@ -6,10 +6,14 @@ activity = "1.11.0"
 lifecycle = "2.9.4"
 navigation = "2.9.5"
 work = "2.10.5"
-media3 = "1.8.0"
 adaptive = "1.1.0"
 jna = "5.17.0"
 junit = "4.13.2"
+robolectric = "4.16"
+androidx-test-core = "1.7.0"
+androidx-test-junit = "1.3.0"
+androidx-test-runner = "1.7.0"
+ktlint-plugin = "13.1.0"
 
 [libraries]
 androidx-core = { module = "androidx.core:core-ktx", version = "1.17.0" }
@@ -18,8 +22,7 @@ androidx-lifecycle-runtime = { module = "androidx.lifecycle:lifecycle-runtime-kt
 androidx-lifecycle-viewmodel-compose = { module = "androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "lifecycle" }
 androidx-navigation-compose = { module = "androidx.navigation:navigation-compose", version.ref = "navigation" }
 androidx-work-runtime = { module = "androidx.work:work-runtime-ktx", version.ref = "work" }
-androidx-media3-session = { module = "androidx.media3:media3-session", version.ref = "media3" }
-androidx-media3-exoplayer = { module = "androidx.media3:media3-exoplayer", version.ref = "media3" }
+androidx-work-testing = { module = "androidx.work:work-testing", version.ref = "work" }
 androidx-compose-bom = { module = "androidx.compose:compose-bom", version.ref = "compose-bom" }
 androidx-compose-ui = { module = "androidx.compose.ui:ui" }
 androidx-compose-ui-tooling = { module = "androidx.compose.ui:ui-tooling" }
@@ -29,11 +32,18 @@ androidx-compose-material3 = { module = "androidx.compose.material3:material3" }
 androidx-compose-material3-adaptive = { module = "androidx.compose.material3.adaptive:adaptive", version.ref = "adaptive" }
 androidx-compose-material3-navigation-suite = { module = "androidx.compose.material3:material3-adaptive-navigation-suite", version.ref = "adaptive" }
 androidx-compose-material-icons-extended = { module = "androidx.compose.material:material-icons-extended" }
+androidx-compose-ui-test-junit4 = { module = "androidx.compose.ui:ui-test-junit4" }
+androidx-compose-ui-test-manifest = { module = "androidx.compose.ui:ui-test-manifest" }
 jna = { module = "net.java.dev.jna:jna", version.ref = "jna" }
 rustls-platform-verifier = { module = "rustls:rustls-platform-verifier", version = "0.1.1" }
 junit = { module = "junit:junit", version.ref = "junit" }
+robolectric = { module = "org.robolectric:robolectric", version.ref = "robolectric" }
+androidx-test-core = { module = "androidx.test:core-ktx", version.ref = "androidx-test-core" }
+androidx-test-junit = { module = "androidx.test.ext:junit", version.ref = "androidx-test-junit" }
+androidx-test-runner = { module = "androidx.test:runner", version.ref = "androidx-test-runner" }
 
 [plugins]
 android-application = { id = "com.android.application", version.ref = "agp" }
 kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
 kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+ktlint = { id = "org.jlleitschuh.gradle.ktlint", version.ref = "ktlint-plugin" }

crates/pstr-android/Cargo.toml

@@ -29,6 +29,7 @@ thiserror.workspace = true
 uniffi.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+log = "0.4"
 
 [target.'cfg(target_os = "android")'.dependencies]
 # Match rustls-platform-verifier's JNI types: Java objects from different
@@ -36,4 +37,3 @@ serde_json.workspace = true
 jni = "0.21.1"
 rustls-platform-verifier = "0.6.2"
 android_logger = "0.14"
-log = "0.4"

crates/pstr-app/src/app.rs

@@ -17,6 +17,7 @@ use pstr_core::metadata::{EpisodeGuide, MetadataConfig, MetadataRecord};
 use crate::engine::{
     DownloadItem, DownloadKey, Engine, Event, ImageCache, describe_failures, watch_state,
 };
+use crate::pacing::Pacer;
 use crate::playback::{Playback, PlaybackTarget};
 use crate::ui::player::UpNextCard;
 use crate::{theme, ui};
@@ -51,6 +52,7 @@ impl FrameTimer {
                 Page::Title(_) => "title",
                 Page::Shares => "shares",
                 Page::Downloads => "downloads",
+                Page::Settings => "settings",
                 Page::Player => "player",
             },
         }
@@ -85,6 +87,8 @@ pub enum Page {
     Title(String),
     Shares,
     Downloads,
+    /// How the app looks, how it plays, and what it looks up.
+    Settings,
     /// The picture, filling the window. Leaving this page does not stop
     /// playback — the transport bar at the bottom is how you get back to it.
     Player,
@@ -294,6 +298,9 @@ pub struct App {
     pub offline_files: std::collections::HashSet<DownloadKey>,
     pub confirm_partial_delete: Option<DownloadKey>,
     pub status: Option<Status>,
+    /// The frame ceiling, where this session is pacing itself rather than
+    /// letting vsync do it — see [`crate::pacing`].
+    pacer: Pacer,
 }
 
 impl App {
@@ -344,6 +351,7 @@ impl App {
             offline_files: std::collections::HashSet::new(),
             confirm_partial_delete: None,
             status: None,
+            pacer: Pacer::new(),
         })
     }
 
@@ -896,20 +904,14 @@ impl App {
         ui.horizontal(|ui| {
             ui.add_space(4.0);
             ui.label(
-                egui::RichText::new("proton-stream")
-                    .size(18.0)
+                theme::Role::Heading
+                    .rich("proton-stream")
                     .strong()
                     .color(theme::accent()),
             );
             ui.add_space(12.0);
 
             let on_library = matches!(self.page, Page::Library | Page::Title(_));
-            if ui::tab(ui, on_library, "Library").clicked() {
-                actions.push(Action::Goto(Page::Library));
-            }
-            if ui::tab(ui, self.page == Page::Shares, "Shares").clicked() {
-                actions.push(Action::Goto(Page::Shares));
-            }
             let active = self
                 .downloads
                 .iter()
@@ -922,13 +924,24 @@ impl App {
                     )
                 })
                 .count();
-            let label = if active == 0 {
+            let downloads = if active == 0 {
                 "Downloads".to_owned()
             } else {
                 format!("Downloads ({active})")
             };
-            if ui::tab(ui, self.page == Page::Downloads, &label).clicked() {
-                actions.push(Action::Goto(Page::Downloads));
+            let pages = [Page::Library, Page::Shares, Page::Downloads, Page::Settings];
+            let clicked = ui::tabs(
+                ui,
+                ui.id().with("nav"),
+                &[
+                    ("Library", on_library),
+                    ("Shares", self.page == Page::Shares),
+                    (&downloads, self.page == Page::Downloads),
+                    ("Settings", self.page == Page::Settings),
+                ],
+            );
+            if let Some(index) = clicked {
+                actions.push(Action::Goto(pages[index].clone()));
             }
 
             ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
@@ -965,6 +978,10 @@ impl App {
 
 impl eframe::App for App {
     fn ui(&mut self, ui: &mut egui::Ui, frame: &mut eframe::Frame) {
+        // Before the timer: this is the frame budget being spent waiting, not
+        // the frame taking longer, and `FrameTimer` reports slow frames.
+        self.pacer.wait();
+
         let _timer = FrameTimer::new(&self.page);
         let ctx = ui.ctx().clone();
         let ctx = &ctx;
@@ -1027,7 +1044,7 @@ impl eframe::App for App {
         {
             let mut search = std::mem::take(&mut self.search);
             let neighbours = self.neighbours();
-            let prefs = ui::shares::Prefs {
+            let prefs = ui::settings::Prefs {
                 autoplay: self.engine.playback_prefs().autoplay_next,
                 appearance: self.engine.appearance(),
             };
@@ -1044,6 +1061,7 @@ impl eframe::App for App {
                     NAV_MARGIN.y as i8,
                 )))
                 .show(ui, |ui| {
+                    let shadow = ui.painter().add(egui::Shape::Noop);
                     let background = ui.painter().add(egui::Shape::Noop);
                     self.navigation(ui, &mut actions, &mut search);
                     // Full width from the space the panel was given, height from
@@ -1056,6 +1074,13 @@ impl eframe::App for App {
                     .expand2(NAV_MARGIN);
                     ui.painter()
                         .set(background, theme::bar_shape(ui.ctx(), bar));
+                    // Past the panel's own edge, or the half of the shadow that
+                    // falls on the page below it — the only half worth drawing
+                    // — is clipped away.
+                    ui.painter().with_clip_rect(ui.ctx().viewport_rect()).set(
+                        shadow,
+                        theme::bar_shadow(true).as_shape(bar, egui::CornerRadius::ZERO),
+                    );
                 });
             self.search = search;
 
@@ -1091,6 +1116,22 @@ impl eframe::App for App {
                             .inner_margin(egui::Margin::symmetric(16, 10)),
                     )
                     .show(ui, |ui| {
+                        // Above the bar rather than below it: this one is at the
+                        // bottom of the window, so the page it separates itself
+                        // from is the one over it.
+                        //
+                        // Clipped to the strip it falls on, because a `Frame`
+                        // paints its fill *under* its contents and a shadow
+                        // added here would otherwise lay its opaque middle over
+                        // the bar it is cast by.
+                        let bar = ui.max_rect().expand2(egui::vec2(16.0, 10.0));
+                        let above = egui::Rect::from_min_max(
+                            egui::pos2(bar.left(), bar.top() - 16.0),
+                            egui::pos2(bar.right(), bar.top()),
+                        );
+                        ui.painter()
+                            .with_clip_rect(above)
+                            .add(theme::bar_shadow(false).as_shape(bar, egui::CornerRadius::ZERO));
                         transport_panel(
                             ui,
                             playback.as_ref(),
@@ -1117,7 +1158,7 @@ impl eframe::App for App {
                             } else {
                                 theme::muted()
                             };
-                            ui.label(egui::RichText::new(&line.text).size(12.0).color(colour));
+                            ui.label(theme::Role::Caption.rich(&line.text).color(colour));
                         });
                     // Repaint once the line is due to disappear, or it lingers
                     // until something else happens to cause a frame.
@@ -1159,15 +1200,10 @@ impl eframe::App for App {
                             },
                             &mut actions,
                         ),
-                        Page::Shares => ui::shares::show(
-                            ui,
-                            shares,
-                            form,
-                            settings,
-                            prefs,
-                            api_key,
-                            &mut actions,
-                        ),
+                        Page::Shares => ui::shares::show(ui, shares, form, &mut actions),
+                        Page::Settings => {
+                            ui::settings::show(ui, settings, prefs, api_key, &mut actions)
+                        }
                         Page::Downloads => ui::downloads::show(ui, downloads, &mut actions),
                         // Drawn above, without any of these panels.
                         Page::Player => {}

crates/pstr-app/src/engine.rs

@@ -1622,7 +1622,7 @@ impl Engine {
                             // Only for a title that matched: there is no id to
                             // ask about otherwise.
                             let episodes = match &record.metadata {
-                                Some(found) => episodes_of(&service, title, found).await,
+                                Some(found) => service.title_episodes(title, found).await,
                                 None => Vec::new(),
                             };
                             Ok((record.title_key.clone(), Some(record), episodes))
@@ -1632,7 +1632,7 @@ impl Engine {
                     Work::Episodes(title, found) => Ok((
                         title.key.clone(),
                         None,
-                        episodes_of(&service, title, found).await,
+                        service.title_episodes(title, found).await,
                     )),
                 })
             });
@@ -1744,7 +1744,7 @@ impl Engine {
                 return engine.fail("store the match", error);
             }
 
-            let episodes = episodes_of(&service, &title, &found).await;
+            let episodes = service.title_episodes(&title, &found).await;
             if !episodes.is_empty() {
                 let stored = engine.catalog.lock().set_episode_metadata(
                     &title.key,
@@ -1855,53 +1855,6 @@ enum Work {
     Episodes(Title, Box<pstr_core::metadata::TitleMetadata>),
 }
 
-/// The episode list for a whole title, with a failure treated as an empty one.
-///
-/// Deliberately not fatal to the title it belongs to: a poster and a synopsis
-/// that arrived are worth keeping even when the episode request was the one
-/// that hit the rate limit. The empty result is not cached as an answer — the
-/// next match run asks again — because the only thing that triggers one is a
-/// viewer pressing the button.
-///
-/// The match itself only ever answers for *one* entry, and on a provider that
-/// files each sequel separately — AniList — that entry is season one. So each
-/// further season of the title is searched for by name and its episodes are
-/// tagged with the season they came from; without that, seasons two and three
-/// have no episode names at all. See
-/// [`MetadataService::season_episodes`](pstr_meta::MetadataService::season_episodes).
-async fn episodes_of(
-    service: &MetadataService,
-    title: &Title,
-    found: &pstr_core::metadata::TitleMetadata,
-) -> Vec<pstr_core::metadata::EpisodeMetadata> {
-    let mut episodes = service
-        .episodes(found)
-        .await
-        .inspect_err(|error| tracing::warn!("episodes for {}: {error}", found.name))
-        .unwrap_or_default();
-
-    if !service.splits_seasons() {
-        return episodes;
-    }
-
-    // Season one is what the title's own match already answered for.
-    let later: Vec<u32> = title
-        .seasons
-        .iter()
-        .filter_map(|season| season.number)
-        .filter(|number| *number > 1)
-        .collect();
-    for season in later {
-        match service.season_episodes(title, season).await {
-            Ok(found) => episodes.extend(found),
-            Err(error) => {
-                tracing::warn!("episodes for {} season {season}: {error}", title.name);
-            }
-        }
-    }
-    episodes
-}
-
 /// Unix seconds, for the "when was this asked" columns.
 fn now() -> i64 {
     std::time::SystemTime::now()

crates/pstr-app/src/lib.rs

@@ -21,6 +21,7 @@
 
 pub mod app;
 pub mod engine;
+pub mod pacing;
 pub mod playback;
 pub mod theme;
 pub mod ui;

crates/pstr-app/src/main.rs

@@ -31,7 +31,7 @@ fn main() -> anyhow::Result<()> {
     );
     let dirs = AppDirs::ensure().context("resolve app directories")?;
 
-    let options = eframe::NativeOptions {
+    let mut options = eframe::NativeOptions {
         viewport: egui::ViewportBuilder::default()
             .with_title("proton-stream")
             .with_inner_size([1180.0, 780.0])
@@ -39,6 +39,10 @@ fn main() -> anyhow::Result<()> {
             .with_app_id("io.narl.proton-stream"),
         ..Default::default()
     };
+    // Off on Wayland, where a swap on a window nobody is looking at never
+    // returns and the compositor decides the app has hung. `pstr_app::pacing`
+    // has the whole of it, and caps the frame rate in vsync's place.
+    options.glow_options.vsync = pstr_app::pacing::vsync();
 
     eframe::run_native(
         "proton-stream",

crates/pstr-app/src/pacing.rs

@@ -0,0 +1,186 @@
+//! How often the window is allowed to draw — and why it does not simply let
+//! vsync decide on Wayland.
+//!
+//! ## The bug this exists for
+//!
+//! A Wayland compositor throttles a client by *withholding* the `wl_surface`
+//! frame callback, and it withholds it for as long as the surface is not being
+//! shown — a window on another workspace, or behind a fullscreen one. Mesa's
+//! EGL implements a swap interval of 1 by waiting on exactly that callback, so
+//! `eglSwapBuffers` on a hidden surface does not return late, it does not
+//! return at all:
+//!
+//! ```text
+//!   eframe run_ui_and_paint ─▶ glutin swap_buffers ─▶ eglSwapBuffers
+//!                                                          │
+//!                              wl_display_dispatch_queue ◀─┘   ppoll, forever
+//! ```
+//!
+//! That is the whole of the UI thread, and the same thread is the one that
+//! answers `xdg_wm_base.ping`. Hyprland pings a client it has not heard from
+//! and puts up an "application is not responding" dialog when the pong does not
+//! come, which is what a viewer sees a few seconds after switching away from a
+//! playing window. Nothing is actually wrong — coming back releases the frame
+//! callback and the app carries on — but a dialog offering to kill the player
+//! is not an acceptable way to say "this window is not visible".
+//!
+//! winit cannot rescue this for us: `WindowEvent::Occluded` is X11, macOS and
+//! web only — its Wayland implementation was deliberately removed in 0.29 — so
+//! eframe never learns the window is hidden and keeps painting it.
+//!
+//! ## What is done instead
+//!
+//! On Wayland the swap interval is set to 0 ([`vsync`]), which makes
+//! `eglSwapBuffers` return immediately whether the surface is being shown or
+//! not, and the frame rate is capped here instead ([`Pacer`]). Nothing is lost
+//! by dropping vsync there: a Wayland compositor composites from the last
+//! buffer a client committed, at its own refresh, so a client that commits too
+//! often wastes work but cannot tear. X11 and Windows keep vsync, where a
+//! client really does drive the scanout and hidden windows do not block.
+//!
+//! The cap is a ceiling and not a rate: frames are drawn when something asks
+//! for one — a new mpv frame, an animation, a keystroke — so an idle window
+//! still draws nothing, and a 24 fps film still draws 24 times a second.
+
+use std::time::{Duration, Instant};
+
+/// The default ceiling, in frames a second.
+///
+/// Above the rate of any video this plays and of every animation in the app.
+/// It is deliberately not the display's refresh rate, which neither eframe nor
+/// egui gives us — a window on a 144 Hz panel therefore animates at 60 while
+/// vsync is off. [`CAP_VAR`] is the way out for someone who minds.
+const DEFAULT_CAP: f32 = 60.0;
+
+/// Overrides [`DEFAULT_CAP`]. `0` removes the ceiling altogether.
+const CAP_VAR: &str = "PSTR_FRAME_CAP";
+
+/// Whether this process is talking to a Wayland compositor, decided the way
+/// winit decides it: either variable, non-empty, Wayland first.
+pub fn on_wayland() -> bool {
+    ["WAYLAND_DISPLAY", "WAYLAND_SOCKET"]
+        .iter()
+        .any(|name| std::env::var_os(name).is_some_and(|value| !value.is_empty()))
+}
+
+/// Whether to ask for a swap interval of 1. False on Wayland — see the module
+/// documentation.
+pub fn vsync() -> bool {
+    !on_wayland()
+}
+
+/// The ceiling to pace to, or `None` when vsync is doing the pacing.
+fn cap() -> Option<f32> {
+    if vsync() {
+        return None;
+    }
+    let Ok(value) = std::env::var(CAP_VAR) else {
+        return Some(DEFAULT_CAP);
+    };
+    // Not a number, or a negative one, is a typo rather than a request to
+    // free-run — free-running is what `0` says, explicitly.
+    let parsed = value
+        .trim()
+        .parse::<f32>()
+        .ok()
+        .filter(|fps| fps.is_finite() && *fps >= 0.0);
+    match parsed {
+        Some(fps) if fps > 0.0 => Some(fps),
+        Some(_) => None,
+        None => {
+            tracing::warn!("{CAP_VAR}={value:?} is not a frame rate; using {DEFAULT_CAP}");
+            Some(DEFAULT_CAP)
+        }
+    }
+}
+
+/// Holds the draw loop to a maximum rate.
+///
+/// Sleeping is the only thing that can do this: a frame is under way by the
+/// time the app sees it, and every other source of repaints — mpv, egui's own
+/// animations — asks for the *next* one immediately. The sleep is at most one
+/// frame's worth, which is far inside the several seconds a compositor waits
+/// for a pong.
+pub struct Pacer {
+    interval: Option<Duration>,
+    last: Instant,
+}
+
+impl Default for Pacer {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Pacer {
+    /// The pacer this session wants: capped when vsync is off, a no-op when it
+    /// is on.
+    pub fn new() -> Self {
+        Self::with_cap(cap())
+    }
+
+    fn with_cap(fps: Option<f32>) -> Self {
+        Self {
+            interval: fps.map(|fps| Duration::from_secs_f32(1.0 / fps)),
+            last: Instant::now(),
+        }
+    }
+
+    /// Whether this pacer does anything at all.
+    pub fn is_capped(&self) -> bool {
+        self.interval.is_some()
+    }
+
+    /// Called once at the top of a frame: sleeps out whatever is left of the
+    /// last one's budget.
+    pub fn wait(&mut self) {
+        let Some(interval) = self.interval else {
+            return;
+        };
+        let elapsed = self.last.elapsed();
+        if let Some(left) = interval.checked_sub(elapsed) {
+            std::thread::sleep(left);
+        }
+        self.last = Instant::now();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn an_uncapped_pacer_never_sleeps() {
+        let mut pacer = Pacer::with_cap(None);
+        assert!(!pacer.is_capped());
+        let before = Instant::now();
+        pacer.wait();
+        pacer.wait();
+        assert!(before.elapsed() < Duration::from_millis(50));
+    }
+
+    #[test]
+    fn a_capped_pacer_holds_the_second_frame_back() {
+        let mut pacer = Pacer::with_cap(Some(50.0));
+        assert!(pacer.is_capped());
+        pacer.wait();
+        let before = Instant::now();
+        pacer.wait();
+        // 20 ms apart, less whatever the first call spent. Sleeping is only
+        // ever long, so the lower bound is the one worth asserting on.
+        assert!(
+            before.elapsed() >= Duration::from_millis(10),
+            "second frame was not held back: {:?}",
+            before.elapsed()
+        );
+    }
+
+    #[test]
+    fn a_frame_that_took_longer_than_the_budget_is_not_delayed_further() {
+        let mut pacer = Pacer::with_cap(Some(1000.0));
+        std::thread::sleep(Duration::from_millis(5));
+        let before = Instant::now();
+        pacer.wait();
+        assert!(before.elapsed() < Duration::from_millis(2));
+    }
+}

crates/pstr-app/src/theme.rs

@@ -23,11 +23,11 @@ use std::collections::BTreeMap;
 use std::sync::Arc;
 
 use egui::{
-    Color32, CornerRadius, Rect, Rgba, Stroke, SystemTheme, TextureHandle, TextureOptions, Theme,
+    Color32, CornerRadius, Rect, Stroke, SystemTheme, TextureHandle, TextureOptions, Theme,
     ThemePreference, ViewportCommand, Visuals,
 };
 use parking_lot::RwLock;
-use pstr_core::appearance::{Accent, Appearance, Flavor};
+use pstr_core::appearance::Appearance;
 
 /// Card geometry. The grid is built from these, so a change here moves
 /// everything together.
@@ -36,6 +36,66 @@ pub const CARD_WIDTH: f32 = 232.0;
 pub const CARD_ASPECT: f32 = 9.0 / 16.0;
 pub const CARD_GAP: f32 = 14.0;
 
+/// The type ramp, named once.
+///
+/// Every size in the app comes from here. They used to be literals at the call
+/// site — `.size(17.0)` in one place and `.size(18.0)` in another for the same
+/// kind of heading — which is not a scale, it is forty independent decisions
+/// that happen to be close together. Naming them makes the ramp a thing that
+/// can be changed, and gives the Android client something to match: a shared
+/// palette settles colour, and this settles the other half.
+///
+/// Sizes rather than full `FontId`s because everything here is proportional;
+/// the one monospace style in the app is egui's own, set in [`apply`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Role {
+    /// The name of the thing you are looking at, once per page.
+    Display,
+    /// An empty state, or the heading of a page that has no display line.
+    Title,
+    /// The brand in the nav bar, and a dialog's heading.
+    Heading,
+    /// A run of content under a rule.
+    Section,
+    /// A row that groups the rows under it — a season header.
+    Subhead,
+    /// Everything that is prose.
+    Body,
+    /// The text on a small control.
+    Label,
+    /// Context rather than content: counts, sizes, errors under a field.
+    Caption,
+    /// The smallest thing that stays legible — a badge over artwork.
+    Micro,
+}
+
+impl Role {
+    pub const fn size(self) -> f32 {
+        match self {
+            Self::Display => 26.0,
+            Self::Title => 20.0,
+            Self::Heading => 18.0,
+            Self::Section => 17.0,
+            Self::Subhead => 15.0,
+            Self::Body => 14.0,
+            Self::Label => 13.0,
+            Self::Caption => 12.0,
+            Self::Micro => 11.0,
+        }
+    }
+
+    /// For the hand-painted parts, which lay text out through a `Painter` and
+    /// never see a `RichText`.
+    pub fn font(self) -> egui::FontId {
+        egui::FontId::proportional(self.size())
+    }
+
+    /// For the parts that go through egui's widgets.
+    pub fn rich(self, text: impl Into<String>) -> egui::RichText {
+        egui::RichText::new(text).size(self.size())
+    }
+}
+
 /// Install a real CJK fallback before the default egui fonts.  egui ships a
 /// compact Latin font, but it intentionally does not bundle the multi-megabyte
 /// CJK families.  Native desktops already provide one, so use it when present.
@@ -91,11 +151,12 @@ fn system_cjk_font() -> Option<(std::path::PathBuf, u32)> {
     None
 }
 
-/// Every colour the app draws with, resolved from a [`Flavor`] and an
-/// [`Accent`].
+/// Every colour the app draws with, as egui wants them.
 ///
-/// `Copy`, and small, so reading it is a lock and a memcpy rather than anything
-/// a drawing loop has to think about.
+/// The *choice* of colours is `pstr_core::appearance` — one resolution shared
+/// with the Android client, so a flavour means the same thing on both. This is
+/// only that palette converted into `Color32`, which is a type `pstr-core`
+/// deliberately knows nothing about.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Palette {
     /// Behind everything: the page.
@@ -118,15 +179,54 @@ pub struct Palette {
     /// The accent taken down into the background, for a pressed control and for
     /// selection behind text.
     pub accent_dim: Color32,
-    /// Ink that stays readable on top of the accent. Chosen by the accent's
-    /// luminance, because Catppuccin's dark flavours have *pale* accents and
-    /// white-on-pastel is not readable at 13 px.
+    /// Ink that stays readable on top of the accent.
     pub on_accent: Color32,
     pub danger: Color32,
     /// Whether this is a light theme.
     pub light: bool,
 }
 
+const fn color(rgb: pstr_core::appearance::Rgb) -> Color32 {
+    Color32::from_rgb(rgb.r, rgb.g, rgb.b)
+}
+
+impl Palette {
+    /// The default, spelled out so the global has something to hold before
+    /// [`apply`] first runs — a `Ui` built during startup, or a panic message
+    /// painted before the engine exists, still gets colours.
+    const PROTON: Self = Self::of(pstr_core::appearance::Palette::PROTON);
+
+    const fn of(palette: pstr_core::appearance::Palette) -> Self {
+        Self {
+            background: color(palette.background),
+            surface: color(palette.surface),
+            sunken: color(palette.sunken),
+            card: color(palette.card),
+            card_hover: color(palette.card_hover),
+            border: color(palette.border),
+            text: color(palette.text),
+            muted: color(palette.muted),
+            accent: color(palette.accent),
+            accent_alt: color(palette.accent_alt),
+            accent_dim: color(palette.accent_dim),
+            on_accent: color(palette.on_accent),
+            danger: color(palette.danger),
+            light: palette.light,
+        }
+    }
+
+    /// Resolve a choice into colours.
+    pub fn resolve(appearance: Appearance) -> Self {
+        Self::of(pstr_core::appearance::Palette::resolve(appearance))
+    }
+}
+
+/// Blend two colours in linear light, through the shared implementation.
+fn mix(from: Color32, to: Color32, t: f32) -> Color32 {
+    let rgb = |c: Color32| pstr_core::appearance::Rgb::new(c.r(), c.g(), c.b());
+    color(pstr_core::appearance::mix(rgb(from), rgb(to), t))
+}
+
 /// Which way a gradient runs.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Direction {
@@ -170,6 +270,16 @@ pub fn danger() -> Color32 {
     palette().danger
 }
 
+/// Whether ramps are drawn at all.
+///
+/// Wider than [`gradients`], which also asks whether the *accent* has two hues
+/// to run between. The viewer who turns gradients off is usually on a panel that
+/// bands them into stripes, and that applies to every ramp in the app, not only
+/// the accent's — so the bar fade and the title backdrop ask this one.
+pub fn ramps_on() -> bool {
+    ACTIVE.read().gradients
+}
+
 /// Whether the accent is currently drawn as a gradient.
 ///
 /// True only when the viewer has gradients on *and* the accent is a pair of
@@ -197,6 +307,29 @@ pub fn accent_fill(
     veil(painter, rect, corner_radius, lift);
 }
 
+/// The accent as a shape rather than paint, for the one caller that has to
+/// draw it *behind* something already laid out: the pill that slides between
+/// the tabs in the navigation bar, whose position is only known once every tab
+/// has been placed.
+pub fn accent_shape(
+    ctx: &egui::Context,
+    rect: Rect,
+    corner_radius: impl Into<CornerRadius>,
+) -> egui::Shape {
+    let corner_radius = corner_radius.into();
+    let palette = palette();
+    if !ACTIVE.read().gradients || palette.accent == palette.accent_alt {
+        return egui::epaint::RectShape::filled(rect, corner_radius, palette.accent).into();
+    }
+    let texture = ramp(
+        ctx,
+        palette.accent,
+        palette.accent_alt,
+        Direction::Horizontal,
+    );
+    textured(rect, corner_radius, &texture)
+}
+
 /// The same, for a palette that is not the one on screen: the accent swatches
 /// on the settings page, each of which previews the theme clicking it would
 /// give.
@@ -225,6 +358,27 @@ fn fill(painter: &egui::Painter, rect: Rect, corner_radius: CornerRadius, palett
     painter.add(textured(rect, corner_radius, &texture));
 }
 
+/// A ramp from `color` to nothing, for laying artwork into the page.
+///
+/// The other ramps here run between two opaque colours; this one runs down its
+/// own alpha, so what is under it shows through the far end. That is what makes
+/// a backdrop end in the page rather than in a horizontal line across the
+/// window.
+/// `arriving` is which end of `direction` the colour is solid at: `false` for a
+/// scrim that starts opaque and lets the picture out, `true` for one that lets
+/// the picture *into* the page — which is the one the title backdrop wants,
+/// since the page is below the band.
+pub fn fade_shape(
+    ctx: &egui::Context,
+    rect: Rect,
+    color: Color32,
+    direction: Direction,
+    arriving: bool,
+) -> egui::Shape {
+    let texture = alpha_ramp(ctx, color, direction, arriving);
+    textured(rect, CornerRadius::ZERO, &texture)
+}
+
 /// The one gradient that is not the accent: the top bar, which runs from the
 /// surface colour down into the page so that the join between them is a fade
 /// rather than an edge.
@@ -249,6 +403,56 @@ pub fn bar_shape(ctx: &egui::Context, rect: Rect) -> egui::Shape {
     textured(rect, CornerRadius::ZERO, &texture)
 }
 
+/// The shadow under a raised tile, at `strength` of its full depth.
+///
+/// Depth is the one separator this app has been doing without: everything is
+/// told apart by fill colour, which works until two things that should be at
+/// different heights are the same colour. Kept soft and offset downwards —
+/// a shadow you can see the edge of reads as a border.
+///
+/// Scaled rather than switched on, so it can ride the same hover value as the
+/// border and arrive with it.
+pub fn tile_shadow(strength: f32) -> egui::epaint::Shadow {
+    shadow(strength, [0, 6], 16, 90)
+}
+
+/// The shadow a bar casts onto the page: shallower than a tile's, because a bar
+/// is not floating over the page so much as sitting against it.
+///
+/// `cast_down` for the bar at the top of the window, off for the transport bar
+/// at the bottom — a shadow that falls the same way on both would light the
+/// window from two directions at once.
+pub fn bar_shadow(cast_down: bool) -> egui::epaint::Shadow {
+    shadow(1.0, [0, if cast_down { 4 } else { -4 }], 12, 70)
+}
+
+fn shadow(strength: f32, offset: [i8; 2], blur: u8, alpha: u8) -> egui::epaint::Shadow {
+    let strength = strength.clamp(0.0, 1.0);
+    egui::epaint::Shadow {
+        offset,
+        blur,
+        spread: 0,
+        // A light theme cannot carry the same shadow: the same black over a
+        // near-white page is a smudge, where over a dark one it is barely
+        // visible. Half strength on light, which is roughly where the two read
+        // the same.
+        color: Color32::from_black_alpha(
+            (f32::from(alpha) * strength * if palette().light { 0.5 } else { 1.0 }) as u8,
+        ),
+    }
+}
+
+/// The hover and press film on its own, for a control whose fill was painted by
+/// somebody else — the selected tab, which sits on the pill.
+pub fn veil_over(
+    painter: &egui::Painter,
+    rect: Rect,
+    corner_radius: impl Into<CornerRadius>,
+    lift: f32,
+) {
+    veil(painter, rect, corner_radius.into(), lift);
+}
+
 /// A white or black film over `rect`, for hover and press states. A no-op at
 /// zero, which is the case that matters — most controls are at rest.
 fn veil(painter: &egui::Painter, rect: Rect, corner_radius: CornerRadius, lift: f32) {
@@ -351,13 +555,14 @@ pub fn apply(ctx: &egui::Context, appearance: Appearance) {
         style.spacing.interact_size.y = 30.0;
         style.spacing.scroll.bar_width = 10.0;
 
-        use egui::FontFamily::Proportional;
+        // egui's own style names, pointed at the ramp above so that a stock
+        // widget nobody restyled still lands on it.
         use egui::TextStyle::{Body, Button, Heading, Monospace, Small};
         style.text_styles = [
-            (Heading, egui::FontId::new(26.0, Proportional)),
-            (Body, egui::FontId::new(14.0, Proportional)),
-            (Button, egui::FontId::new(14.0, Proportional)),
-            (Small, egui::FontId::new(11.5, Proportional)),
+            (Heading, Role::Display.font()),
+            (Body, Role::Body.font()),
+            (Button, Role::Body.font()),
+            (Small, Role::Caption.font()),
             (
                 Monospace,
                 egui::FontId::new(12.5, egui::FontFamily::Monospace),
@@ -390,7 +595,10 @@ struct Active {
     /// flavour the window is not wearing are eight ramps that belong to no
     /// palette in particular. Bounded by the number of flavours times the
     /// number of accents, and only the ones actually drawn.
-    ramps: BTreeMap<(u32, u32, bool), TextureHandle>,
+    /// The last field separates a ramp between two colours from one that runs
+    /// down its own alpha — the two would otherwise collide on
+    /// `(colour, transparent)`.
+    ramps: BTreeMap<(u32, u32, bool, u8), TextureHandle>,
 }
 
 static ACTIVE: RwLock<Active> = RwLock::new(Active {
@@ -401,17 +609,54 @@ static ACTIVE: RwLock<Active> = RwLock::new(Active {
 
 /// A ramp between two colours, built once and kept.
 fn ramp(ctx: &egui::Context, from: Color32, to: Color32, direction: Direction) -> TextureHandle {
+    build(ctx, from, to, direction, 0, mix)
+}
+
+/// A ramp from `color` down to nothing.
+///
+/// The alpha is what is interpolated; the colour stays put. Fading the colour
+/// as well would take a dark scrim through grey on its way out, which over
+/// artwork reads as fog rather than as the picture ending.
+fn alpha_ramp(
+    ctx: &egui::Context,
+    color: Color32,
+    direction: Direction,
+    arriving: bool,
+) -> TextureHandle {
+    build(
+        ctx,
+        color,
+        Color32::TRANSPARENT,
+        direction,
+        1 + u8::from(arriving),
+        move |from, _, t| from.gamma_multiply(if arriving { t } else { 1.0 - t }),
+    )
+}
+
+/// One texture per ramp, built on demand and kept until the palette changes.
+///
+/// `kind` says which of the three kinds this is, so that a fade and a colour
+/// ramp between the same two ends do not come out sharing one texture.
+fn build(
+    ctx: &egui::Context,
+    from: Color32,
+    to: Color32,
+    direction: Direction,
+    kind: u8,
+    stop: impl Fn(Color32, Color32, f32) -> Color32,
+) -> TextureHandle {
     let key = (
         u32::from_le_bytes(from.to_array()),
         u32::from_le_bytes(to.to_array()),
         direction == Direction::Vertical,
+        kind,
     );
     if let Some(texture) = ACTIVE.read().ramps.get(&key) {
         return texture.clone();
     }
 
     let pixels: Vec<Color32> = (0..RAMP_STOPS)
-        .map(|stop| mix(from, to, stop as f32 / (RAMP_STOPS - 1) as f32))
+        .map(|index| stop(from, to, index as f32 / (RAMP_STOPS - 1) as f32))
         .collect();
     let size = match direction {
         Direction::Horizontal => [RAMP_STOPS, 1],
@@ -437,353 +682,10 @@ fn ramp(ctx: &egui::Context, from: Color32, to: Color32, direction: Direction) -
 /// light, which is what this does.
 const RAMP_STOPS: usize = 64;
 
-/// Blend two colours in linear light. Mixing in sRGB darkens the middle of a
-/// ramp between saturated hues, which is exactly where a gradient is looked at.
-fn mix(from: Color32, to: Color32, t: f32) -> Color32 {
-    let from = Rgba::from(from);
-    let to = Rgba::from(to);
-    Color32::from(from * (1.0 - t) + to * t)
-}
-
-/// Relative luminance, in linear light, as WCAG defines it.
-fn luminance(color: Color32) -> f32 {
-    let rgba = Rgba::from(color);
-    0.2126 * rgba.r() + 0.7152 * rgba.g() + 0.0722 * rgba.b()
-}
-
-/// WCAG contrast between two opaque colours: 1.0 for a colour against itself,
-/// 21.0 for black against white.
-fn contrast(one: Color32, other: Color32) -> f32 {
-    let (one, other) = (luminance(one), luminance(other));
-    (one.max(other) + 0.05) / (one.min(other) + 0.05)
-}
-
-/// The least contrast a label gets anywhere along a gradient between two
-/// colours. Sampled rather than solved: the worst point is not always an end,
-/// because the ink can be brighter than one end and darker than the other.
-fn worst_contrast(from: Color32, to: Color32, ink: Color32) -> f32 {
-    (0..=4)
-        .map(|step| contrast(mix(from, to, step as f32 / 4.0), ink))
-        .fold(f32::INFINITY, f32::min)
-}
-
-/// The least contrast the app will accept between a label and the fill under
-/// it: WCAG AA for large text, which is what wears the accent — button labels,
-/// a tab, a play glyph, never body copy.
-const MIN_CONTRAST: f32 = 3.0;
-
-/// One flavour's raw colours, named as Catppuccin names them.
-///
-/// Stored rather than computed: these are somebody else's palette, and the
-/// point of using it is to use it exactly.
-#[derive(Clone, Copy)]
-struct Ramp {
-    base: Color32,
-    mantle: Color32,
-    crust: Color32,
-    surface0: Color32,
-    surface1: Color32,
-    subtext0: Color32,
-    text: Color32,
-    pink: Color32,
-    mauve: Color32,
-    sky: Color32,
-    sapphire: Color32,
-    blue: Color32,
-    lavender: Color32,
-    teal: Color32,
-    green: Color32,
-    peach: Color32,
-    yellow: Color32,
-    red: Color32,
-    light: bool,
-}
-
-const fn rgb(hex: u32) -> Color32 {
-    Color32::from_rgb(
-        ((hex >> 16) & 0xff) as u8,
-        ((hex >> 8) & 0xff) as u8,
-        (hex & 0xff) as u8,
-    )
-}
-
-/// The palette this app shipped with, extended to the hues an accent can be.
-///
-/// Only `mauve` — Proton purple — and `red` are from the original; the rest are
-/// chosen to sit on a near-black base at roughly the saturation that one does,
-/// which is a good deal hotter than any Catppuccin flavour.
-const PROTON: Ramp = Ramp {
-    base: rgb(0x0e0e12),
-    mantle: rgb(0x17171d),
-    crust: rgb(0x0a0a0d),
-    surface0: rgb(0x1e1e26),
-    surface1: rgb(0x2a2a35),
-    subtext0: rgb(0x8e8e9c),
-    text: rgb(0xeaeaf0),
-    pink: rgb(0xff5fbe),
-    mauve: rgb(0x7d4dff),
-    sky: rgb(0x4dd2ff),
-    sapphire: rgb(0x3a8fc4),
-    blue: rgb(0x3f6fe0),
-    lavender: rgb(0xa68cff),
-    teal: rgb(0x3fd6b8),
-    green: rgb(0x56d364),
-    peach: rgb(0xff9a4d),
-    yellow: rgb(0xffd166),
-    red: rgb(0xe05561),
-    light: false,
-};
-
-const LATTE: Ramp = Ramp {
-    base: rgb(0xeff1f5),
-    mantle: rgb(0xe6e9ef),
-    crust: rgb(0xdce0e8),
-    surface0: rgb(0xccd0da),
-    surface1: rgb(0xbcc0cc),
-    subtext0: rgb(0x6c6f85),
-    text: rgb(0x4c4f69),
-    pink: rgb(0xea76cb),
-    mauve: rgb(0x8839ef),
-    sky: rgb(0x04a5e5),
-    sapphire: rgb(0x209fb5),
-    blue: rgb(0x1e66f5),
-    lavender: rgb(0x7287fd),
-    teal: rgb(0x179299),
-    green: rgb(0x40a02b),
-    peach: rgb(0xfe640b),
-    yellow: rgb(0xdf8e1d),
-    red: rgb(0xd20f39),
-    light: true,
-};
-
-const FRAPPE: Ramp = Ramp {
-    base: rgb(0x303446),
-    mantle: rgb(0x292c3c),
-    crust: rgb(0x232634),
-    surface0: rgb(0x414559),
-    surface1: rgb(0x51576d),
-    subtext0: rgb(0xa5adce),
-    text: rgb(0xc6d0f5),
-    pink: rgb(0xf4b8e4),
-    mauve: rgb(0xca9ee6),
-    sky: rgb(0x99d1db),
-    sapphire: rgb(0x85c1dc),
-    blue: rgb(0x8caaee),
-    lavender: rgb(0xbabbf1),
-    teal: rgb(0x81c8be),
-    green: rgb(0xa6d189),
-    peach: rgb(0xef9f76),
-    yellow: rgb(0xe5c890),
-    red: rgb(0xe78284),
-    light: false,
-};
-
-const MACCHIATO: Ramp = Ramp {
-    base: rgb(0x24273a),
-    mantle: rgb(0x1e2030),
-    crust: rgb(0x181926),
-    surface0: rgb(0x363a4f),
-    surface1: rgb(0x494d64),
-    subtext0: rgb(0xa5adcb),
-    text: rgb(0xcad3f5),
-    pink: rgb(0xf5bde6),
-    mauve: rgb(0xc6a0f6),
-    sky: rgb(0x91d7e3),
-    sapphire: rgb(0x7dc4e4),
-    blue: rgb(0x8aadf4),
-    lavender: rgb(0xb7bdf8),
-    teal: rgb(0x8bd5ca),
-    green: rgb(0xa6da95),
-    peach: rgb(0xf5a97f),
-    yellow: rgb(0xeed49f),
-    red: rgb(0xed8796),
-    light: false,
-};
-
-const MOCHA: Ramp = Ramp {
-    base: rgb(0x1e1e2e),
-    mantle: rgb(0x181825),
-    crust: rgb(0x11111b),
-    surface0: rgb(0x313244),
-    surface1: rgb(0x45475a),
-    subtext0: rgb(0xa6adc8),
-    text: rgb(0xcdd6f4),
-    pink: rgb(0xf5c2e7),
-    mauve: rgb(0xcba6f7),
-    sky: rgb(0x89dceb),
-    sapphire: rgb(0x74c7ec),
-    blue: rgb(0x89b4fa),
-    lavender: rgb(0xb4befe),
-    teal: rgb(0x94e2d5),
-    green: rgb(0xa6e3a1),
-    peach: rgb(0xfab387),
-    yellow: rgb(0xf9e2af),
-    red: rgb(0xf38ba8),
-    light: false,
-};
-
-impl Ramp {
-    const fn of(flavor: Flavor) -> Self {
-        match flavor {
-            Flavor::Proton => PROTON,
-            Flavor::Latte => LATTE,
-            Flavor::Frappe => FRAPPE,
-            Flavor::Macchiato => MACCHIATO,
-            Flavor::Mocha => MOCHA,
-        }
-    }
-
-    /// The accent, and the hue a gradient in it runs into.
-    ///
-    /// The partners are neighbours on the wheel rather than complements: a
-    /// gradient across half the spectrum passes through a colour that belongs
-    /// to neither end, and on a seek bar that reads as a bug. The exception is
-    /// [`Accent::PinkSky`], which is the whole point of that entry.
-    const fn accents(&self, accent: Accent) -> (Color32, Color32) {
-        match accent {
-            Accent::Mauve => (self.mauve, self.blue),
-            Accent::Pink => (self.pink, self.mauve),
-            Accent::Sky => (self.sky, self.sapphire),
-            Accent::PinkSky => (self.pink, self.sky),
-            Accent::Lavender => (self.lavender, self.blue),
-            Accent::Blue => (self.blue, self.sapphire),
-            Accent::Teal => (self.teal, self.green),
-            Accent::Peach => (self.peach, self.yellow),
-        }
-    }
-}
-
-impl Palette {
-    /// The default, spelled out as a constant so the global has something to
-    /// hold before [`apply`] first runs — a `Ui` built during startup, or a
-    /// panic message painted before the engine exists, still gets colours.
-    const PROTON: Self = Self {
-        background: PROTON.base,
-        surface: PROTON.mantle,
-        sunken: PROTON.crust,
-        card: PROTON.surface0,
-        card_hover: PROTON.surface1,
-        border: rgb(0x262630),
-        text: PROTON.text,
-        muted: PROTON.subtext0,
-        accent: PROTON.mauve,
-        accent_alt: PROTON.blue,
-        accent_dim: rgb(0x5333ad),
-        on_accent: PROTON.text,
-        danger: PROTON.red,
-        light: false,
-    };
-
-    /// Resolve a choice into colours.
-    pub fn resolve(appearance: Appearance) -> Self {
-        let ramp = Ramp::of(appearance.flavor);
-        let (accent, partner) = ramp.accents(appearance.accent);
-        // Catppuccin's Latte accents are tuned to be *read*, on a light page,
-        // at body-text weight — which makes them mid-luminance, and a
-        // mid-luminance fill is one that neither black nor white sits on. They
-        // are taken down in value here, and only here: the hue and the
-        // saturation are Latte's, so it still looks like Latte, and a label on
-        // a button is legible.
-        let deepen = |color: Color32| {
-            if ramp.light {
-                mix(color, Color32::BLACK, 0.30)
-            } else {
-                color
-            }
-        };
-        let accent = deepen(accent);
-        let accent_alt = if appearance.gradients {
-            deepen(partner)
-        } else {
-            accent
-        };
-
-        // Ink that survives on the accent. The flavour's own reading first —
-        // pale text on a dark theme — and the opposite when that does not clear
-        // the bar, which on Catppuccin's dark flavours is most of the time:
-        // their accents are *pastel*, and white on #f5c2e7 is not a label.
-        //
-        // Latte's darkest colour is its body text, and even that is only #4c4f69,
-        // so the dark side is taken a third of the way to black.
-        let ink_dark = if ramp.light {
-            mix(ramp.text, Color32::BLACK, 0.35)
-        } else {
-            ramp.crust
-        };
-        let ink_light = if ramp.light { ramp.base } else { ramp.text };
-        let on_accent = if worst_contrast(accent, accent_alt, ink_light) >= MIN_CONTRAST {
-            ink_light
-        } else {
-            ink_dark
-        };
-
-        Self {
-            background: ramp.base,
-            surface: ramp.mantle,
-            sunken: ramp.crust,
-            card: ramp.surface0,
-            card_hover: ramp.surface1,
-            border: ramp.surface1,
-            text: ramp.text,
-            muted: ramp.subtext0,
-            accent,
-            accent_alt,
-            // Behind text, so it is the accent taken most of the way back to
-            // the page: a selection in a saturated hue is a selection nobody
-            // can read through.
-            accent_dim: mix(accent, ramp.base, if ramp.light { 0.55 } else { 0.45 }),
-            on_accent,
-            danger: ramp.red,
-            light: ramp.light,
-        }
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    #[test]
-    fn every_flavour_and_accent_resolves_to_readable_ink() {
-        for flavor in Flavor::ALL {
-            for accent in Accent::ALL {
-                let palette = Palette::resolve(Appearance {
-                    flavor,
-                    accent,
-                    gradients: true,
-                });
-                let ratio = worst_contrast(palette.accent, palette.accent_alt, palette.on_accent);
-                assert!(
-                    ratio >= MIN_CONTRAST,
-                    "{flavor:?}/{accent:?}: contrast {ratio:.2}",
-                );
-            }
-        }
-    }
-
-    #[test]
-    fn only_the_light_flavour_reports_itself_light() {
-        for flavor in Flavor::ALL {
-            let palette = Palette::resolve(Appearance {
-                flavor,
-                ..Appearance::default()
-            });
-            assert_eq!(palette.light, flavor.is_light());
-            // And the page is on the right side of the middle either way.
-            assert_eq!(luminance(palette.background) > 0.5, flavor.is_light());
-        }
-    }
-
-    #[test]
-    fn turning_gradients_off_leaves_one_colour_to_draw() {
-        let flat = Palette::resolve(Appearance {
-            accent: Accent::PinkSky,
-            gradients: false,
-            ..Appearance::default()
-        });
-        assert_eq!(flat.accent, flat.accent_alt);
-    }
-
     #[test]
     fn the_shipped_default_is_the_palette_that_was_here_before() {
         let resolved = Palette::resolve(Appearance::default());
@@ -795,11 +697,13 @@ mod tests {
 
     #[test]
     fn a_ramp_runs_from_one_colour_to_the_other() {
+        // The blend itself is `pstr_core::appearance`'s and tested there; what
+        // is checked here is that the conversion in and out of `Color32` is
+        // not lossy at the ends.
         let from = Color32::from_rgb(0, 0, 0);
         let to = Color32::from_rgb(255, 255, 255);
         assert_eq!(mix(from, to, 0.0), from);
         assert_eq!(mix(from, to, 1.0), to);
-        assert!(luminance(mix(from, to, 0.5)) > luminance(from));
-        assert!(luminance(mix(from, to, 0.5)) < luminance(to));
+        assert_ne!(mix(from, to, 0.5), from);
     }
 }

crates/pstr-app/src/ui/downloads.rs

@@ -32,7 +32,7 @@ pub fn show(ui: &mut egui::Ui, downloads: &[DownloadItem], actions: &mut Vec<Act
             .filter(|item| item.state == DownloadState::Completed)
             .count();
 
-        ui.label(egui::RichText::new(title).size(17.0).strong());
+        ui.label(theme::Role::Section.rich(title).strong());
         let totals_known = group.iter().all(|item| item.total > 0);
         ui.horizontal(|ui| {
             if totals_known {
@@ -145,7 +145,11 @@ fn row(ui: &mut egui::Ui, item: &DownloadItem, actions: &mut Vec<Action>) {
                             }
                         }
                         DownloadState::Completed => {
-                            if ui.button("Make online-only").clicked() {
+                            if ui
+                                .button("Delete")
+                                .on_hover_text("Delete the offline copy; keep the online source")
+                                .clicked()
+                            {
                                 actions.push(Action::RemoveDownload(item.key.clone(), false));
                             }
                         }

crates/pstr-app/src/ui/library.rs

@@ -93,6 +93,9 @@ fn continue_row(
                             subtitle: remaining,
                             progress: episode.progress().map(|value| value as f32),
                             badge: episode.numbering(),
+                            // A shelf that scrolls sideways has no right edge
+                            // to reach, so nothing to flex to.
+                            width: theme::CARD_WIDTH,
                         },
                     )
                     .clicked();
@@ -107,9 +110,14 @@ fn continue_row(
 
 /// Every title, wrapped to the window.
 fn grid(ui: &mut egui::Ui, art: &mut Art<'_>, titles: &[&Title], actions: &mut Vec<Action>) {
-    let columns = ui::columns(ui.available_width());
-    for row in titles.chunks(columns) {
+    let grid = ui::columns(ui.available_width());
+    for row in titles.chunks(grid.columns) {
         ui.horizontal(|ui| {
+            // The gap the width was divided around, so what is drawn matches
+            // what was measured. egui's default item spacing is narrower, and
+            // the difference times the column count is a visible drift towards
+            // the left edge.
+            ui.spacing_mut().item_spacing.x = theme::CARD_GAP;
             for title in row {
                 let clicked = ui::card(
                     ui,
@@ -121,6 +129,7 @@ fn grid(ui: &mut egui::Ui, art: &mut Art<'_>, titles: &[&Title], actions: &mut V
                         // What a film is says itself in the subtitle below the
                         // card; a second `Film` over the poster is noise.
                         badge: None,
+                        width: grid.width,
                     },
                 )
                 .clicked();
@@ -163,8 +172,8 @@ fn empty_state(ui: &mut egui::Ui, actions: &mut Vec<Action>) {
     ui.vertical_centered(|ui| {
         ui.add_space(120.0);
         ui.label(
-            egui::RichText::new("Nothing in the library yet")
-                .size(20.0)
+            theme::Role::Title
+                .rich("Nothing in the library yet")
                 .strong(),
         );
         ui.add_space(6.0);

crates/pstr-app/src/ui/matcher.rs

@@ -49,8 +49,8 @@ pub fn show(
             ui.set_width(620.0);
 
             ui.label(
-                egui::RichText::new(format!("Match “{}”", matcher.title_name))
-                    .size(18.0)
+                theme::Role::Heading
+                    .rich(format!("Match “{}”", matcher.title_name))
                     .strong()
                     .color(theme::text()),
             );
@@ -66,7 +66,7 @@ pub fn show(
             ui.add_space(10.0);
 
             if let Some(error) = &matcher.error {
-                ui.label(egui::RichText::new(error).size(12.0).color(theme::danger()));
+                ui.label(theme::Role::Caption.rich(error).color(theme::danger()));
                 ui.add_space(6.0);
             }
 
@@ -212,8 +212,8 @@ fn row(ui: &mut egui::Ui, art: &mut Art<'_>, found: &TitleMetadata) -> egui::Res
                 ui.add_space(10.0);
                 ui.vertical(|ui| {
                     ui.label(
-                        egui::RichText::new(&found.name)
-                            .size(14.0)
+                        theme::Role::Body
+                            .rich(&found.name)
                             .strong()
                             .color(theme::text()),
                     );
@@ -224,7 +224,7 @@ fn row(ui: &mut egui::Ui, art: &mut Art<'_>, found: &TitleMetadata) -> egui::Res
                     if let Some(overview) = &found.overview {
                         let mut job = egui::text::LayoutJob::simple(
                             overview.replace('\n', " "),
-                            egui::FontId::proportional(11.5),
+                            theme::Role::Caption.font(),
                             theme::muted(),
                             ui.available_width(),
                         );

crates/pstr-app/src/ui/mod.rs

@@ -7,6 +7,7 @@ pub mod downloads;
 pub mod library;
 pub mod matcher;
 pub mod player;
+pub mod settings;
 pub mod shares;
 pub mod title;
 pub mod transport;
@@ -114,8 +115,8 @@ pub fn format_size(bytes: i64) -> String {
 pub fn section(ui: &mut egui::Ui, text: &str) {
     ui.add_space(6.0);
     ui.label(
-        egui::RichText::new(text)
-            .size(17.0)
+        theme::Role::Section
+            .rich(text)
             .strong()
             .color(theme::text()),
     );
@@ -124,18 +125,81 @@ pub fn section(ui: &mut egui::Ui, text: &str) {
 
 /// Small grey text, for everything that is context rather than content.
 pub fn muted(text: impl Into<String>) -> egui::RichText {
-    egui::RichText::new(text).size(12.0).color(theme::muted())
+    theme::Role::Caption.rich(text).color(theme::muted())
 }
 
 /// The one button style that means "this is the action".
 pub fn accent_button(ui: &mut egui::Ui, text: &str) -> egui::Response {
-    filled(ui, text, true, Vec2::new(0.0, 0.0))
+    filled(ui, text, Fill::Accent, Vec2::new(0.0, 0.0))
 }
 
-/// A tab in the top bar. The selected one wears the accent; the others are text
-/// until the pointer is over them.
-pub fn tab(ui: &mut egui::Ui, selected: bool, text: &str) -> egui::Response {
-    filled(ui, text, selected, Vec2::new(4.0, 0.0))
+/// What [`filled`] paints behind its label.
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum Fill {
+    /// The accent, gradient and all.
+    Accent,
+    /// Nothing — something else already painted the accent here, and the label
+    /// only has to be legible on it.
+    Ink,
+    /// Nothing at rest, the hover colour under the pointer.
+    None,
+}
+
+/// A row of tabs with one accent pill that slides between them.
+///
+/// Drawn as a row rather than a tab at a time because the pill has to be
+/// painted *behind* labels whose positions are not known until they have been
+/// laid out, and because a pill that moves has to be one pill: a per-tab fill
+/// can only ever cross-fade, which reads as two things blinking rather than one
+/// thing travelling.
+///
+/// Returns the index that was clicked, if any.
+pub fn tabs(ui: &mut egui::Ui, id: egui::Id, items: &[(&str, bool)]) -> Option<usize> {
+    // Reserved now, filled in below: everything drawn after this lands on top
+    // of it whatever it turns out to be.
+    let pill = ui.painter().add(egui::Shape::Noop);
+
+    let mut clicked = None;
+    let mut selected = None;
+    for (index, (text, is_selected)) in items.iter().enumerate() {
+        let response = tab(ui, *is_selected, text);
+        if *is_selected {
+            selected = Some(response.rect);
+        }
+        if response.clicked() {
+            clicked = Some(index);
+        }
+    }
+
+    if let Some(target) = selected {
+        // Interpolating the edges rather than the centre and the width keeps
+        // the pill from overshooting when it moves between tabs of different
+        // lengths — both edges arrive at the same time.
+        let ctx = ui.ctx();
+        let left = ctx.animate_value_with_time(id.with("left"), target.left(), 0.16);
+        let right = ctx.animate_value_with_time(id.with("right"), target.right(), 0.16);
+        let rect = Rect::from_min_max(
+            egui::pos2(left, target.top()),
+            egui::pos2(right, target.bottom()),
+        );
+        ui.painter().set(
+            pill,
+            theme::accent_shape(ui.ctx(), rect, CornerRadius::same(8)),
+        );
+    }
+
+    clicked
+}
+
+/// One tab. The selected one is ink on the pill [`tabs`] draws; the others are
+/// text until the pointer is over them.
+fn tab(ui: &mut egui::Ui, selected: bool, text: &str) -> egui::Response {
+    filled(
+        ui,
+        text,
+        if selected { Fill::Ink } else { Fill::None },
+        Vec2::new(4.0, 0.0),
+    )
 }
 
 /// A button painted by hand, so that "filled with the accent" can mean a
@@ -144,7 +208,7 @@ pub fn tab(ui: &mut egui::Ui, selected: bool, text: &str) -> egui::Response {
 /// `egui::Button` takes a single `Color32` and there is no way in to give it
 /// anything else, so the fill, the label and the hover states are all drawn
 /// here. Everything else — sizing, padding, the click — is still egui's.
-fn filled(ui: &mut egui::Ui, text: &str, accented: bool, extra: Vec2) -> egui::Response {
+fn filled(ui: &mut egui::Ui, text: &str, fill: Fill, extra: Vec2) -> egui::Response {
     let padding = ui.spacing().button_padding + extra;
     let galley = ui.painter().layout_no_wrap(
         text.to_owned(),
@@ -162,23 +226,35 @@ fn filled(ui: &mut egui::Ui, text: &str, accented: bool, extra: Vec2) -> egui::R
     }
 
     let radius = CornerRadius::same(8);
-    let lift = if response.is_pointer_button_down_on() {
-        -0.14
-    } else if response.hovered() {
-        0.10
-    } else {
-        0.0
-    };
+    // Eased rather than switched, so the veil arrives over a few frames instead
+    // of appearing whole the moment the pointer crosses the edge. The press is
+    // quicker than the hover: a click should feel like it registered, not like
+    // it was considered.
+    let ctx = ui.ctx().clone();
+    let hover = ctx.animate_bool_with_time(response.id.with("hover"), response.hovered(), 0.10);
+    let press = ctx.animate_bool_with_time(
+        response.id.with("press"),
+        response.is_pointer_button_down_on(),
+        0.05,
+    );
+    let lift = 0.10 * hover * (1.0 - press) - 0.14 * press;
 
-    let ink = if accented {
-        theme::accent_fill(ui.painter(), rect, radius, lift);
-        theme::on_accent()
-    } else {
-        if response.hovered() {
-            ui.painter().rect_filled(rect, radius, theme::card_hover());
-            theme::text()
-        } else {
-            theme::muted()
+    let ink = match fill {
+        Fill::Accent => {
+            theme::accent_fill(ui.painter(), rect, radius, lift);
+            theme::on_accent()
+        }
+        // The pill is already under this one; only the veil is missing.
+        Fill::Ink => {
+            theme::veil_over(ui.painter(), rect, radius, lift);
+            theme::on_accent()
+        }
+        Fill::None => {
+            if hover > 0.0 {
+                ui.painter()
+                    .rect_filled(rect, radius, theme::card_hover().gamma_multiply(hover));
+            }
+            theme::muted().lerp_to_gamma(theme::text(), hover)
         }
     };
 
@@ -197,6 +273,12 @@ pub struct Card<'a> {
     pub progress: Option<f32>,
     /// A short label in the corner — `S01E04`.
     pub badge: Option<String>,
+    /// How wide to draw it.
+    ///
+    /// A grid flexes this so its rows reach the right edge of the window; a
+    /// sideways-scrolling shelf has no edge to reach and passes
+    /// [`theme::CARD_WIDTH`].
+    pub width: f32,
 }
 
 /// Draw one tile and report whether it was clicked.
@@ -208,7 +290,7 @@ pub struct Card<'a> {
 /// the title, usually. The gap it leaves is filled with the card colour, which
 /// reads as deliberate in a way a stretched poster does not.
 pub fn card(ui: &mut egui::Ui, card: Card<'_>) -> egui::Response {
-    let width = theme::CARD_WIDTH;
+    let width = card.width;
     let image_height = (width * theme::CARD_ASPECT).round();
     // Two lines of name plus one of subtitle. Fixed, because the tile is
     // allocated before the name is laid out — and because a grid whose rows are
@@ -223,16 +305,46 @@ pub fn card(ui: &mut egui::Ui, card: Card<'_>) -> egui::Response {
     }
 
     let image_rect = Rect::from_min_size(rect.min, Vec2::new(width, image_height));
-    let hovered = response.hovered();
+    // Hover is a value, not a flag: the border, the lift and the shadow all
+    // ride it, so they arrive together rather than each snapping on its own.
+    // egui drives this from wall-clock time, so it is the same speed whatever
+    // the frame rate — and it needs no state kept here.
+    let hover =
+        ui.ctx()
+            .animate_bool_with_time(response.id.with("hover"), response.hovered(), 0.12);
+    // The picture arrives whenever its download finishes, several frames after
+    // the tile first drew. Fading it in over the placeholder turns a wall of
+    // letters popping into stills into one settle.
+    let art_in = ui
+        .ctx()
+        .animate_bool_with_time(response.id.with("art"), card.art.is_some(), 0.22);
     let painter = ui.painter();
 
+    if hover > 0.0 {
+        painter.add(theme::tile_shadow(hover).as_shape(image_rect, radius));
+    }
     painter.rect_filled(image_rect, radius, theme::card());
 
+    // Under the picture, not instead of it: it is what shows through while the
+    // art fades in, and it is the whole tile when there is no art to come.
+    if art_in < 1.0 {
+        painter.text(
+            image_rect.center(),
+            Align2::CENTER_CENTER,
+            initials(card.name),
+            egui::FontId::proportional(28.0),
+            theme::muted().gamma_multiply(1.0 - art_in),
+        );
+    }
+
+    // White because a textured rect *multiplies* its fill by the texture; the
+    // alpha on it is what fades the picture in.
+    let ink = Color32::WHITE.gamma_multiply(art_in);
     match &card.art {
         Some((texture, ArtShape::Landscape)) => {
             let size = texture.size_vec2();
             painter.add(
-                egui::epaint::RectShape::filled(image_rect, radius, Color32::WHITE)
+                egui::epaint::RectShape::filled(image_rect, radius, ink)
                     .with_texture(texture.id(), cover_uv(size, image_rect.size())),
             );
         }
@@ -241,7 +353,7 @@ pub fn card(ui: &mut egui::Ui, card: Card<'_>) -> egui::Response {
                 egui::epaint::RectShape::filled(
                     contain_rect(texture.size_vec2(), image_rect),
                     radius,
-                    Color32::WHITE,
+                    ink,
                 )
                 .with_texture(
                     texture.id(),
@@ -249,24 +361,13 @@ pub fn card(ui: &mut egui::Ui, card: Card<'_>) -> egui::Response {
                 ),
             );
         }
-        None => {
-            painter.text(
-                image_rect.center(),
-                Align2::CENTER_CENTER,
-                initials(card.name),
-                egui::FontId::proportional(28.0),
-                theme::muted(),
-            );
-        }
+        None => {}
     }
 
     if let Some(badge) = &card.badge {
         let anchor = image_rect.right_top() + Vec2::new(-8.0, 8.0);
-        let galley = painter.layout_no_wrap(
-            badge.clone(),
-            egui::FontId::proportional(11.0),
-            Color32::WHITE,
-        );
+        let galley =
+            painter.layout_no_wrap(badge.clone(), theme::Role::Micro.font(), Color32::WHITE);
         let background = Rect::from_min_size(
             anchor - Vec2::new(galley.size().x + 10.0, 0.0),
             galley.size() + Vec2::new(10.0, 4.0),
@@ -314,11 +415,11 @@ pub fn card(ui: &mut egui::Ui, card: Card<'_>) -> egui::Response {
         theme::accent_fill(&clipped_painter, played, played_radius, 0.0);
     }
 
-    if hovered {
+    if hover > 0.0 {
         painter.rect_stroke(
             image_rect,
             radius,
-            Stroke::new(2.0, theme::accent()),
+            Stroke::new(2.0, theme::accent().gamma_multiply(hover)),
             egui::StrokeKind::Inside,
         );
     }
@@ -333,12 +434,10 @@ pub fn card(ui: &mut egui::Ui, card: Card<'_>) -> egui::Response {
     // the line below it.
     let mut job = egui::text::LayoutJob::simple(
         card.name.to_string(),
-        egui::FontId::proportional(14.0),
-        if hovered {
-            Color32::WHITE
-        } else {
-            theme::text()
-        },
+        theme::Role::Body.font(),
+        // Towards white as the pointer arrives, so the name lifts with the
+        // border rather than staying put while everything around it moves.
+        theme::text().lerp_to_gamma(Color32::WHITE, hover),
         width,
     );
     job.wrap.max_rows = 2;
@@ -350,7 +449,7 @@ pub fn card(ui: &mut egui::Ui, card: Card<'_>) -> egui::Response {
         text_rect.min + Vec2::new(0.0, name_height + 2.0),
         Align2::LEFT_TOP,
         card.subtitle,
-        egui::FontId::proportional(11.5),
+        theme::Role::Caption.font(),
         theme::muted(),
     );
 
@@ -396,10 +495,33 @@ fn initials(name: &str) -> String {
         .collect()
 }
 
-/// How many cards fit, and the gap that leaves them evenly spread.
-pub fn columns(available: f32) -> usize {
-    (((available + theme::CARD_GAP) / (theme::CARD_WIDTH + theme::CARD_GAP)).floor() as usize)
-        .max(1)
+/// How a grid divides the width it was given.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Grid {
+    pub columns: usize,
+    /// What each card should be drawn at, so the row reaches both edges.
+    pub width: f32,
+}
+
+/// Fit as many cards as will go, then widen them to use the rest.
+///
+/// [`theme::CARD_WIDTH`] is a *minimum*, not the width. Dividing by it and
+/// flooring — which is what this used to do — leaves up to one whole card of
+/// dead space at the right of every row, and on a wide window that reads as a
+/// layout that failed to line up rather than as a margin.
+pub fn columns(available: f32) -> Grid {
+    let columns = (((available + theme::CARD_GAP) / (theme::CARD_WIDTH + theme::CARD_GAP)).floor()
+        as usize)
+        .max(1);
+    // The gaps come out of the width before it is split. Floored, because a
+    // fraction of a point times four columns is enough to push the last card
+    // onto a row of its own. A window too narrow for even one full card gets a
+    // card narrower than the minimum, which is better than one clipped by the
+    // edge.
+    let width = ((available - theme::CARD_GAP * (columns - 1) as f32) / columns as f32)
+        .floor()
+        .max(1.0);
+    Grid { columns, width }
 }
 
 #[cfg(test)]
@@ -454,7 +576,31 @@ mod tests {
 
     #[test]
     fn column_count_never_reaches_zero() {
-        assert_eq!(columns(0.0), 1);
-        assert!(columns(2000.0) > 1);
+        assert_eq!(columns(0.0).columns, 1);
+        assert!(columns(2000.0).columns > 1);
+    }
+
+    #[test]
+    fn a_row_of_cards_fills_the_width_it_was_given() {
+        // The defect this replaced: floor(available / CARD_WIDTH) cards at a
+        // fixed width leave up to one card's worth of the window empty.
+        for available in [400.0, 813.0, 1280.0, 1920.5, 3440.0] {
+            let grid = columns(available);
+            let used =
+                grid.width * grid.columns as f32 + theme::CARD_GAP * (grid.columns - 1) as f32;
+            assert!(used <= available, "{available}: {used} overflows the row");
+            assert!(
+                available - used < grid.columns as f32 + 1.0,
+                "{available}: {} left over",
+                available - used,
+            );
+        }
+    }
+
+    #[test]
+    fn cards_never_go_below_the_minimum_while_they_still_fit() {
+        for available in [500.0, 900.0, 2400.0] {
+            assert!(columns(available).width >= theme::CARD_WIDTH);
+        }
     }
 }

crates/pstr-app/src/ui/player.rs

@@ -287,7 +287,7 @@ fn waiting(ui: &mut egui::Ui, playback: &Playback, rect: Rect) {
         rect.center() - Vec2::new(0.0, 18.0),
         Align2::CENTER_CENTER,
         &playback.target.title_name,
-        egui::FontId::proportional(20.0),
+        theme::Role::Title.font(),
         theme::text(),
     );
     painter.text(
@@ -298,7 +298,7 @@ fn waiting(ui: &mut egui::Ui, playback: &Playback, rect: Rect) {
         } else {
             "playing in mpv's own window"
         },
-        egui::FontId::proportional(13.0),
+        theme::Role::Label.font(),
         theme::muted(),
     );
 }
@@ -313,14 +313,14 @@ fn between(ui: &mut egui::Ui, opening: Option<&str>, rect: Rect, actions: &mut V
         rect.center() - Vec2::new(0.0, 16.0),
         Align2::CENTER_CENTER,
         "Up next",
-        egui::FontId::proportional(14.0),
+        theme::Role::Body.font(),
         theme::muted(),
     );
     ui.painter().text(
         rect.center() + Vec2::new(0.0, 12.0),
         Align2::CENTER_CENTER,
         opening.unwrap_or("opening…"),
-        egui::FontId::proportional(20.0),
+        theme::Role::Title.font(),
         theme::text(),
     );
 
@@ -361,7 +361,7 @@ fn skip(
     // recap" are different lengths, and one constant leaves the shorter of them
     // adrift in a box of its own whitespace, which is what made this read as a
     // rectangle with some text in it instead of a button.
-    let font = egui::FontId::proportional(14.0);
+    let font = theme::Role::Body.font();
     let text_width = ui
         .painter()
         .layout_no_wrap(label.to_owned(), font.clone(), Color32::WHITE)
@@ -440,8 +440,8 @@ fn up_next_card(
                 ui.set_width(size.x - 28.0);
                 ui.horizontal(|ui| {
                     ui.label(
-                        egui::RichText::new("Up next")
-                            .size(12.0)
+                        theme::Role::Caption
+                            .rich("Up next")
                             .strong()
                             .color(Color32::from_white_alpha(200)),
                     );
@@ -449,16 +449,16 @@ fn up_next_card(
                         // Rounded up, so a card that says "1s" is never
                         // followed by a second of nothing happening.
                         ui.label(
-                            egui::RichText::new(format!("in {}s", card.seconds.ceil() as u32))
-                                .size(12.0)
+                            theme::Role::Caption
+                                .rich(format!("in {}s", card.seconds.ceil() as u32))
                                 .color(theme::accent()),
                         );
                     });
                 });
                 ui.add(
                     egui::Label::new(
-                        egui::RichText::new(&card.caption)
-                            .size(14.0)
+                        theme::Role::Body
+                            .rich(&card.caption)
                             .strong()
                             .color(Color32::WHITE),
                     )
@@ -533,7 +533,7 @@ fn chrome(
         |ui| {
             if ui
                 .add(
-                    egui::Button::new(egui::RichText::new("Library").size(13.0))
+                    egui::Button::new(theme::Role::Label.rich("Library"))
                         .fill(Color32::from_black_alpha(160))
                         .corner_radius(CornerRadius::same(8))
                         .min_size(Vec2::new(96.0, 32.0)),
@@ -546,14 +546,14 @@ fn chrome(
             ui.add_space(14.0);
             ui.vertical(|ui| {
                 ui.label(
-                    egui::RichText::new(&playback.target.title_name)
-                        .size(18.0)
+                    theme::Role::Heading
+                        .rich(&playback.target.title_name)
                         .strong()
                         .color(Color32::WHITE),
                 );
                 ui.label(
-                    egui::RichText::new(playback.target.caption())
-                        .size(13.0)
+                    theme::Role::Label
+                        .rich(playback.target.caption())
                         .color(Color32::from_white_alpha(190)),
                 );
             });
@@ -561,7 +561,7 @@ fn chrome(
             ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
                 if ui
                     .add(
-                        egui::Button::new(egui::RichText::new("⛶").size(15.0))
+                        egui::Button::new(theme::Role::Subhead.rich("⛶"))
                             .fill(Color32::from_black_alpha(160))
                             .corner_radius(CornerRadius::same(8))
                             .min_size(Vec2::new(38.0, 32.0)),

crates/pstr-app/src/ui/settings.rs

@@ -0,0 +1,269 @@
+//! Settings: how the app looks, how it plays, and what it asks the internet.
+//!
+//! Split out of the shares page, where these lived because that was the only
+//! page with a form on it. Nobody looking for the theme looks under the page
+//! that manages Proton Drive links, and a page that is half link management and
+//! half preferences is two pages.
+
+use pstr_core::appearance::{Accent, Appearance, Flavor};
+use pstr_core::metadata::{MetadataConfig, ProviderId};
+
+use crate::app::Action;
+use crate::theme;
+use crate::ui;
+
+/// The settings that are a single value rather than a form.
+///
+/// Bundled for the same reason [`crate::ui::Art`] is: they arrive together,
+/// they are read-only, and passing them one by one is what pushed this
+/// function past the argument count anybody can read.
+#[derive(Debug, Clone, Copy)]
+pub struct Prefs {
+    pub autoplay: bool,
+    pub appearance: Appearance,
+}
+
+pub fn show(
+    ui: &mut egui::Ui,
+    settings: &mut MetadataConfig,
+    prefs: Prefs,
+    api_key: &mut String,
+    actions: &mut Vec<Action>,
+) {
+    egui::ScrollArea::vertical()
+        .auto_shrink([false, false])
+        .show(ui, |ui| {
+            appearance_form(ui, prefs.appearance, actions);
+
+            ui.add_space(28.0);
+            playback_form(ui, prefs.autoplay, actions);
+
+            ui.add_space(28.0);
+            metadata_form(ui, settings, api_key, actions);
+        });
+}
+
+/// The theme: a flavour, an accent, and whether the accent is a gradient.
+///
+/// Every control here repaints the whole window the moment it is clicked —
+/// there is no "apply" — because the preview *is* the app. A swatch row that
+/// only changed a small square would be asking someone to imagine the result.
+fn appearance_form(ui: &mut egui::Ui, appearance: Appearance, actions: &mut Vec<Action>) {
+    ui::section(ui, "Appearance");
+
+    egui::Frame::new()
+        .fill(theme::card())
+        .corner_radius(egui::CornerRadius::same(8))
+        .inner_margin(egui::Margin::same(14))
+        .show(ui, |ui| {
+            ui.set_width(ui.available_width().min(640.0));
+
+            ui.label(ui::muted("Palette"));
+            for flavor in Flavor::ALL {
+                if ui
+                    .radio(appearance.flavor == flavor, flavor.label())
+                    .on_hover_text(flavor.description())
+                    .clicked()
+                    && appearance.flavor != flavor
+                {
+                    actions.push(Action::SetAppearance(Appearance {
+                        flavor,
+                        ..appearance
+                    }));
+                }
+            }
+
+            ui.add_space(12.0);
+            ui.label(ui::muted("Accent"));
+            ui.horizontal_wrapped(|ui| {
+                for accent in Accent::ALL {
+                    if swatch(ui, appearance, accent).clicked() && appearance.accent != accent {
+                        actions.push(Action::SetAppearance(Appearance {
+                            accent,
+                            ..appearance
+                        }));
+                    }
+                }
+            });
+
+            ui.add_space(12.0);
+            let mut gradients = appearance.gradients;
+            if ui
+                .checkbox(&mut gradients, "Fade the accent into a second colour")
+                .on_hover_text(
+                    "Off draws it flat — better on a panel that bands a gradient into stripes",
+                )
+                .changed()
+            {
+                actions.push(Action::SetAppearance(Appearance {
+                    gradients,
+                    ..appearance
+                }));
+            }
+        });
+}
+
+/// One accent, drawn in the colours it would actually produce.
+///
+/// Resolved against the *selected* flavour rather than the active palette, so
+/// the row previews what clicking it would give rather than what is on screen.
+fn swatch(ui: &mut egui::Ui, appearance: Appearance, accent: Accent) -> egui::Response {
+    let selected = appearance.accent == accent;
+    let size = egui::Vec2::new(52.0, 26.0);
+    let (rect, response) = ui.allocate_exact_size(size, egui::Sense::click());
+    if ui.is_rect_visible(rect) {
+        let palette = theme::Palette::resolve(Appearance {
+            accent,
+            ..appearance
+        });
+        let radius = egui::CornerRadius::same(6);
+        theme::swatch_fill(ui.painter(), rect, radius, &palette);
+        if selected {
+            // A ring rather than a tick: the tick would have to be drawn in an
+            // ink that reads on eight different fills.
+            ui.painter().rect_stroke(
+                rect.expand(2.0),
+                egui::CornerRadius::same(8),
+                egui::Stroke::new(2.0, theme::text()),
+                egui::StrokeKind::Outside,
+            );
+        }
+    }
+    response
+        .on_hover_text(accent.label())
+        .on_hover_cursor(egui::CursorIcon::PointingHand)
+}
+
+/// The handful of playback settings that are not per-file.
+///
+/// Volume, audio language and subtitle language are all set from the player
+/// itself, where a viewer can hear the result — only autoplay has no natural
+/// home there, because by the time it matters the episode is over.
+fn playback_form(ui: &mut egui::Ui, autoplay: bool, actions: &mut Vec<Action>) {
+    ui::section(ui, "Playback");
+
+    egui::Frame::new()
+        .fill(theme::card())
+        .corner_radius(egui::CornerRadius::same(8))
+        .inner_margin(egui::Margin::same(14))
+        .show(ui, |ui| {
+            ui.set_width(ui.available_width().min(640.0));
+
+            let mut enabled = autoplay;
+            if ui
+                .checkbox(&mut enabled, "Play the next episode automatically")
+                .on_hover_text("Only when an episode reaches its end, never after a failure")
+                .changed()
+            {
+                actions.push(Action::SetAutoplay(enabled));
+            }
+            ui.label(ui::muted(
+                "Volume, audio language and subtitles are set from the player, and remembered \
+                 from there.",
+            ));
+        });
+}
+
+/// Enrichment: the switch, the provider, and the cost of turning it on.
+///
+/// The privacy note is not decoration and it is not in a tooltip. Turning this
+/// on sends the titles in someone's library to a third party, which is a thing
+/// they can only agree to if they are told — so it is stated where the switch
+/// is, before the switch, in the same size as everything else.
+fn metadata_form(
+    ui: &mut egui::Ui,
+    settings: &mut MetadataConfig,
+    api_key: &mut String,
+    actions: &mut Vec<Action>,
+) {
+    ui::section(ui, "Posters and descriptions");
+
+    egui::Frame::new()
+        .fill(theme::card())
+        .corner_radius(egui::CornerRadius::same(8))
+        .inner_margin(egui::Margin::same(14))
+        .show(ui, |ui| {
+            ui.set_width(ui.available_width().min(640.0));
+
+            ui.label(ui::muted(
+                "A share filled by the Proton Drive desktop client carries no thumbnails, so \
+                 without this every tile is a pair of initials. Turning it on sends the titles \
+                 in your library — not your files, and nothing about what you have watched — to \
+                 the provider you choose, over HTTPS, each time a new one appears.",
+            ));
+            ui.add_space(10.0);
+
+            let mut changed = false;
+            let mut enabled = settings.enabled;
+            if ui
+                .checkbox(&mut enabled, "Look up posters and descriptions")
+                .changed()
+            {
+                settings.enabled = enabled;
+                changed = true;
+            }
+
+            if settings.enabled {
+                ui.add_space(10.0);
+                ui.label(ui::muted("Provider"));
+                for provider in ProviderId::ALL {
+                    if ui
+                        .radio(settings.provider == provider, provider.label())
+                        .on_hover_text(provider.description())
+                        .clicked()
+                        && settings.provider != provider
+                    {
+                        settings.provider = provider;
+                        changed = true;
+                    }
+                }
+
+                if settings.provider.needs_api_key() {
+                    ui.add_space(10.0);
+                    ui.label(ui::muted(format!("{} API key", settings.provider.label())));
+                    ui.horizontal(|ui| {
+                        ui.add(
+                            egui::TextEdit::singleline(api_key)
+                                .password(true)
+                                .hint_text("v3 API key")
+                                .desired_width(300.0),
+                        );
+                        if ui.button("Save key").clicked() {
+                            actions.push(Action::SetApiKey {
+                                provider: settings.provider,
+                                key: std::mem::take(api_key),
+                            });
+                        }
+                    });
+                    ui.label(ui::muted(
+                        "Stored in your system keyring, never in a config file. Leave the box \
+                         empty and save to forget it.",
+                    ));
+                }
+
+                ui.add_space(12.0);
+                ui.horizontal(|ui| {
+                    if ui::accent_button(ui, "Match the library").clicked() {
+                        actions.push(Action::MatchTitles { force: false });
+                    }
+                    if ui
+                        .button("Match everything again")
+                        .on_hover_text("Ask about every title, including ones already matched")
+                        .clicked()
+                    {
+                        actions.push(Action::MatchTitles { force: true });
+                    }
+                });
+            } else {
+                ui.add_space(6.0);
+                ui.label(ui::muted(
+                    "Off. Nothing is sent anywhere, and turning it off also deletes the answers \
+                     already stored.",
+                ));
+            }
+
+            if changed {
+                actions.push(Action::SetMetadataConfig(settings.clone()));
+            }
+        });
+}

crates/pstr-app/src/ui/shares.rs

@@ -7,33 +7,12 @@
 //! typed.
 
 use pstr_core::Share;
-use pstr_core::appearance::{Accent, Appearance, Flavor};
-use pstr_core::metadata::{MetadataConfig, ProviderId};
 
 use crate::app::{Action, ShareForm};
 use crate::theme;
 use crate::ui;
 
-/// The settings on this page that are a single value rather than a form.
-///
-/// Bundled for the same reason [`crate::ui::Art`] is: they arrive together,
-/// they are read-only, and passing them one by one is what pushed this
-/// function past the argument count anybody can read.
-#[derive(Debug, Clone, Copy)]
-pub struct Prefs {
-    pub autoplay: bool,
-    pub appearance: Appearance,
-}
-
-pub fn show(
-    ui: &mut egui::Ui,
-    shares: &[Share],
-    form: &mut ShareForm,
-    settings: &mut MetadataConfig,
-    prefs: Prefs,
-    api_key: &mut String,
-    actions: &mut Vec<Action>,
-) {
+pub fn show(ui: &mut egui::Ui, shares: &[Share], form: &mut ShareForm, actions: &mut Vec<Action>) {
     egui::ScrollArea::vertical()
         .auto_shrink([false, false])
         .show(ui, |ui| {
@@ -47,240 +26,6 @@ pub fn show(
 
             ui.add_space(22.0);
             add_form(ui, form, actions);
-
-            ui.add_space(28.0);
-            playback_form(ui, prefs.autoplay, actions);
-
-            ui.add_space(28.0);
-            appearance_form(ui, prefs.appearance, actions);
-
-            ui.add_space(28.0);
-            metadata_form(ui, settings, api_key, actions);
-        });
-}
-
-/// The theme: a flavour, an accent, and whether the accent is a gradient.
-///
-/// Every control here repaints the whole window the moment it is clicked —
-/// there is no "apply" — because the preview *is* the app. A swatch row that
-/// only changed a small square would be asking someone to imagine the result.
-fn appearance_form(ui: &mut egui::Ui, appearance: Appearance, actions: &mut Vec<Action>) {
-    ui::section(ui, "Appearance");
-
-    egui::Frame::new()
-        .fill(theme::card())
-        .corner_radius(egui::CornerRadius::same(8))
-        .inner_margin(egui::Margin::same(14))
-        .show(ui, |ui| {
-            ui.set_width(ui.available_width().min(640.0));
-
-            ui.label(ui::muted("Palette"));
-            for flavor in Flavor::ALL {
-                if ui
-                    .radio(appearance.flavor == flavor, flavor.label())
-                    .on_hover_text(flavor.description())
-                    .clicked()
-                    && appearance.flavor != flavor
-                {
-                    actions.push(Action::SetAppearance(Appearance {
-                        flavor,
-                        ..appearance
-                    }));
-                }
-            }
-
-            ui.add_space(12.0);
-            ui.label(ui::muted("Accent"));
-            ui.horizontal_wrapped(|ui| {
-                for accent in Accent::ALL {
-                    if swatch(ui, appearance, accent).clicked() && appearance.accent != accent {
-                        actions.push(Action::SetAppearance(Appearance {
-                            accent,
-                            ..appearance
-                        }));
-                    }
-                }
-            });
-
-            ui.add_space(12.0);
-            let mut gradients = appearance.gradients;
-            if ui
-                .checkbox(&mut gradients, "Fade the accent into a second colour")
-                .on_hover_text(
-                    "Off draws it flat — better on a panel that bands a gradient into stripes",
-                )
-                .changed()
-            {
-                actions.push(Action::SetAppearance(Appearance {
-                    gradients,
-                    ..appearance
-                }));
-            }
-        });
-}
-
-/// One accent, drawn in the colours it would actually produce.
-///
-/// Resolved against the *selected* flavour rather than the active palette, so
-/// the row previews what clicking it would give rather than what is on screen.
-fn swatch(ui: &mut egui::Ui, appearance: Appearance, accent: Accent) -> egui::Response {
-    let selected = appearance.accent == accent;
-    let size = egui::Vec2::new(52.0, 26.0);
-    let (rect, response) = ui.allocate_exact_size(size, egui::Sense::click());
-    if ui.is_rect_visible(rect) {
-        let palette = theme::Palette::resolve(Appearance {
-            accent,
-            ..appearance
-        });
-        let radius = egui::CornerRadius::same(6);
-        theme::swatch_fill(ui.painter(), rect, radius, &palette);
-        if selected {
-            // A ring rather than a tick: the tick would have to be drawn in an
-            // ink that reads on eight different fills.
-            ui.painter().rect_stroke(
-                rect.expand(2.0),
-                egui::CornerRadius::same(8),
-                egui::Stroke::new(2.0, theme::text()),
-                egui::StrokeKind::Outside,
-            );
-        }
-    }
-    response
-        .on_hover_text(accent.label())
-        .on_hover_cursor(egui::CursorIcon::PointingHand)
-}
-
-/// Enrichment: the switch, the provider, and the cost of turning it on.
-///
-/// The privacy note is not decoration and it is not in a tooltip. Turning this
-/// on sends the titles in someone's library to a third party, which is a thing
-/// they can only agree to if they are told — so it is stated where the switch
-/// is, before the switch, in the same size as everything else.
-/// The handful of playback settings that are not per-file.
-///
-/// Volume, audio language and subtitle language are all set from the player
-/// itself, where a viewer can hear the result — only autoplay has no natural
-/// home there, because by the time it matters the episode is over.
-fn playback_form(ui: &mut egui::Ui, autoplay: bool, actions: &mut Vec<Action>) {
-    ui::section(ui, "Playback");
-
-    egui::Frame::new()
-        .fill(theme::card())
-        .corner_radius(egui::CornerRadius::same(8))
-        .inner_margin(egui::Margin::same(14))
-        .show(ui, |ui| {
-            ui.set_width(ui.available_width().min(640.0));
-
-            let mut enabled = autoplay;
-            if ui
-                .checkbox(&mut enabled, "Play the next episode automatically")
-                .on_hover_text("Only when an episode reaches its end, never after a failure")
-                .changed()
-            {
-                actions.push(Action::SetAutoplay(enabled));
-            }
-            ui.label(ui::muted(
-                "Volume, audio language and subtitles are set from the player, and remembered \
-                 from there.",
-            ));
-        });
-}
-
-fn metadata_form(
-    ui: &mut egui::Ui,
-    settings: &mut MetadataConfig,
-    api_key: &mut String,
-    actions: &mut Vec<Action>,
-) {
-    ui::section(ui, "Posters and descriptions");
-
-    egui::Frame::new()
-        .fill(theme::card())
-        .corner_radius(egui::CornerRadius::same(8))
-        .inner_margin(egui::Margin::same(14))
-        .show(ui, |ui| {
-            ui.set_width(ui.available_width().min(640.0));
-
-            ui.label(ui::muted(
-                "A share filled by the Proton Drive desktop client carries no thumbnails, so \
-                 without this every tile is a pair of initials. Turning it on sends the titles \
-                 in your library — not your files, and nothing about what you have watched — to \
-                 the provider you choose, over HTTPS, each time a new one appears.",
-            ));
-            ui.add_space(10.0);
-
-            let mut changed = false;
-            let mut enabled = settings.enabled;
-            if ui
-                .checkbox(&mut enabled, "Look up posters and descriptions")
-                .changed()
-            {
-                settings.enabled = enabled;
-                changed = true;
-            }
-
-            if settings.enabled {
-                ui.add_space(10.0);
-                ui.label(ui::muted("Provider"));
-                for provider in ProviderId::ALL {
-                    if ui
-                        .radio(settings.provider == provider, provider.label())
-                        .on_hover_text(provider.description())
-                        .clicked()
-                        && settings.provider != provider
-                    {
-                        settings.provider = provider;
-                        changed = true;
-                    }
-                }
-
-                if settings.provider.needs_api_key() {
-                    ui.add_space(10.0);
-                    ui.label(ui::muted(format!("{} API key", settings.provider.label())));
-                    ui.horizontal(|ui| {
-                        ui.add(
-                            egui::TextEdit::singleline(api_key)
-                                .password(true)
-                                .hint_text("v3 API key")
-                                .desired_width(300.0),
-                        );
-                        if ui.button("Save key").clicked() {
-                            actions.push(Action::SetApiKey {
-                                provider: settings.provider,
-                                key: std::mem::take(api_key),
-                            });
-                        }
-                    });
-                    ui.label(ui::muted(
-                        "Stored in your system keyring, never in a config file. Leave the box \
-                         empty and save to forget it.",
-                    ));
-                }
-
-                ui.add_space(12.0);
-                ui.horizontal(|ui| {
-                    if ui::accent_button(ui, "Match the library").clicked() {
-                        actions.push(Action::MatchTitles { force: false });
-                    }
-                    if ui
-                        .button("Match everything again")
-                        .on_hover_text("Ask about every title, including ones already matched")
-                        .clicked()
-                    {
-                        actions.push(Action::MatchTitles { force: true });
-                    }
-                });
-            } else {
-                ui.add_space(6.0);
-                ui.label(ui::muted(
-                    "Off. Nothing is sent anywhere, and turning it off also deletes the answers \
-                     already stored.",
-                ));
-            }
-
-            if changed {
-                actions.push(Action::SetMetadataConfig(settings.clone()));
-            }
         });
 }
 

crates/pstr-app/src/ui/title.rs

@@ -44,13 +44,13 @@ pub fn show(
             for (index, season) in title.seasons.iter().enumerate() {
                 let open = index == 0 || title.seasons.len() == 1;
                 egui::CollapsingHeader::new(
-                    egui::RichText::new(format!(
-                        "{}  ·  {}",
-                        season.label(),
-                        ui::library::plural(season.episodes.len(), "episode")
-                    ))
-                    .size(15.0)
-                    .strong(),
+                    theme::Role::Subhead
+                        .rich(format!(
+                            "{}  ·  {}",
+                            season.label(),
+                            ui::library::plural(season.episodes.len(), "episode")
+                        ))
+                        .strong(),
                 )
                 .id_salt(("season", index))
                 .default_open(open)
@@ -58,13 +58,17 @@ pub fn show(
                     let season_keys: Vec<_> = season.episodes.iter().map(key_of).collect();
                     let all_offline = season_keys.iter().all(|key| offline.files.contains(key));
                     if all_offline {
-                        if ui.button("Make season online-only").clicked() {
+                        if ui
+                            .button("Delete season")
+                            .on_hover_text("Delete the offline copies; keep the online source")
+                            .clicked()
+                        {
                             for key in season_keys {
                                 actions.push(Action::RemoveDownload(key, false));
                             }
                         }
                     } else if ui
-                        .button("Make season offline")
+                        .button("Download season")
                         .on_hover_text("Download every episode in this season")
                         .clicked()
                     {
@@ -98,22 +102,34 @@ fn header(
     let record = art.metadata.get(&title.key);
     let found = record.and_then(|record| record.metadata.clone());
     let by_hand = record.is_some_and(|record| record.manual);
+    // Asked for once and used twice: the same picture is the poster beside the
+    // text and the banner behind all of it.
+    let picture = art.of(title);
 
+    // Reserved before the header is laid out, because the band is as tall as
+    // whatever the header comes to — a fixed height would clip a long overview
+    // on one title and leave a gap under a short one on the next.
+    let backdrop = picture
+        .as_ref()
+        .map(|(texture, _)| (texture.clone(), ui.painter().add(egui::Shape::Noop)));
+
+    ui.add_space(6.0);
     ui.horizontal_top(|ui| {
         ui::card(
             ui,
             Card {
-                art: art.of(title),
+                art: picture,
                 name: &title.name,
                 subtitle: String::new(),
                 progress: title.resume().and_then(|e| e.progress()).map(|v| v as f32),
                 badge: None,
+                width: theme::CARD_WIDTH,
             },
         );
 
         ui.add_space(18.0);
         ui.vertical(|ui| {
-            ui.label(egui::RichText::new(&title.name).size(26.0).strong());
+            ui.label(theme::Role::Display.rich(&title.name).strong());
             // The provider's name for it, when it is not the one the files use.
             // Worth showing rather than replacing the filename's: a viewer
             // should be able to tell what the match actually matched.
@@ -147,13 +163,17 @@ fn header(
                     let title_keys: Vec<_> = title.episodes().map(key_of).collect();
                     let all_offline = title_keys.iter().all(|key| offline.files.contains(key));
                     if all_offline {
-                        if ui.button("Make show online-only").clicked() {
+                        if ui
+                            .button("Delete show")
+                            .on_hover_text("Delete the offline copies; keep the online source")
+                            .clicked()
+                        {
                             for key in title_keys {
                                 actions.push(Action::RemoveDownload(key, false));
                             }
                         }
                     } else if ui
-                        .button("Make show offline")
+                        .button("Download show")
                         .on_hover_text("Download every episode for disconnected playback")
                         .clicked()
                     {
@@ -220,6 +240,101 @@ fn header(
             }
         });
     });
+
+    if let Some((texture, index)) = backdrop {
+        ui.add_space(10.0);
+        band(ui, &texture, index);
+    }
+}
+
+/// The picture again, across the whole width, behind the header.
+///
+/// The one piece of this page that had to wait for artwork to exist at all: the
+/// providers already hand back a picture and its shape, so a backdrop costs no
+/// new request — only somewhere to put it.
+///
+/// Three shapes over one another, in this order: the picture, a flat veil of the
+/// page colour so text laid over it stays readable whatever the still happens to
+/// be, and a fade into the page along the bottom so the band ends rather than
+/// stops.
+fn band(ui: &mut egui::Ui, texture: &egui::TextureHandle, index: egui::layers::ShapeIdx) {
+    // Full width of the window, not of the content: the panel's own margin is
+    // what the band has to reach past, or it reads as a picture in a box.
+    const BLEED: f32 = 18.0;
+    let content = ui.min_rect();
+    let rect = egui::Rect::from_min_max(
+        egui::pos2(ui.max_rect().left() - BLEED, content.top()),
+        egui::pos2(ui.max_rect().right() + BLEED, content.bottom()),
+    );
+
+    // Past the panel margin, or the bleed is trimmed off at exactly the edge it
+    // exists to cross.
+    let painter = ui.painter().with_clip_rect(rect);
+    // Every layer of the band goes into the one slot reserved before the header
+    // was laid out. Painting the veils here, after the fact, would put them over
+    // the name and the overview as well as the still — which is the picture
+    // being readable at the cost of the text it exists behind.
+    let mut layers: Vec<egui::Shape> = vec![
+        egui::epaint::RectShape::filled(rect, egui::CornerRadius::ZERO, egui::Color32::WHITE)
+            .with_texture(
+                texture.id(),
+                super::cover_uv(texture.size_vec2(), rect.size()),
+            )
+            .into(),
+    ];
+    // Heavier than it looks: a still is arbitrary, and the one it lands on may
+    // be a white frame. This is the difference between a hero and an unreadable
+    // page.
+    //
+    // Two coats rather than one heavy one. The first is flat and near-opaque —
+    // enough on its own that body text over the busiest frame still reads. The
+    // second is the picture's own contrast being knocked back further behind the
+    // left half, where the poster, the name and the overview actually sit; the
+    // right half keeps more of the still, so the band is still a picture.
+    //
+    // Heavier still when there is no fade coming, since then these are the only
+    // things standing between the text and the picture.
+    let ramps = theme::ramps_on();
+    layers.push(
+        egui::epaint::RectShape::filled(
+            rect,
+            egui::CornerRadius::ZERO,
+            theme::background().gamma_multiply(if ramps { 0.90 } else { 0.94 }),
+        )
+        .into(),
+    );
+    if ramps {
+        let text_side = egui::Rect::from_min_max(
+            rect.min,
+            egui::pos2(rect.left() + rect.width() * 0.72, rect.bottom()),
+        );
+        layers.push(theme::fade_shape(
+            ui.ctx(),
+            text_side,
+            theme::background(),
+            theme::Direction::Horizontal,
+            // Solid at the left, where the poster and the text are.
+            false,
+        ));
+    }
+
+    // A viewer with ramps off is on a panel that bands them; a 120-point ramp
+    // of one hue is exactly the case that shows it. The band then ends at its
+    // own edge, which is the honest version of the same thing.
+    if ramps {
+        let fade =
+            egui::Rect::from_min_max(egui::pos2(rect.left(), rect.bottom() - 120.0), rect.max);
+        layers.push(theme::fade_shape(
+            ui.ctx(),
+            fade,
+            theme::background(),
+            theme::Direction::Vertical,
+            // Solid at the bottom, where the page it hands over to is.
+            true,
+        ));
+    }
+
+    painter.set(index, egui::Shape::Vec(layers));
 }
 
 /// What the provider had to say. Only ever drawn under a match.
@@ -229,14 +344,7 @@ fn description(ui: &mut egui::Ui, found: &TitleMetadata) {
         ui.add_space(6.0);
     }
     if let Some(overview) = &found.overview {
-        ui.add(
-            egui::Label::new(
-                egui::RichText::new(overview)
-                    .size(13.0)
-                    .color(theme::text()),
-            )
-            .wrap(),
-        );
+        ui.add(egui::Label::new(theme::Role::Label.rich(overview).color(theme::text())).wrap());
     }
     if let Some(url) = &found.url {
         ui.add_space(8.0);
@@ -324,10 +432,7 @@ fn episode_row(
                 // carries a checkbox, and a click that means "seen" must never
                 // be one that starts a 1.4 GiB stream instead.
                 if ui
-                    .add(
-                        egui::Button::new(egui::RichText::new("▶").size(13.0))
-                            .fill(theme::card_hover()),
-                    )
+                    .add(egui::Button::new(theme::Role::Label.rich("▶")).fill(theme::card_hover()))
                     .on_hover_text("Play")
                     .clicked()
                 {
@@ -337,7 +442,7 @@ fn episode_row(
                 let current = offline.downloads.iter().find(|item| item.key == key);
                 if offline.files.contains(&key) {
                     if ui
-                        .small_button("Online-only")
+                        .small_button("Delete")
                         .on_hover_text("Delete the offline copy; keep the online source")
                         .clicked()
                     {
@@ -443,11 +548,7 @@ fn episode_row(
                         // saying so on the row rather than only when a click on
                         // it comes back with "has no content".
                         Some(0) => {
-                            ui.label(
-                                egui::RichText::new("empty")
-                                    .size(12.0)
-                                    .color(theme::danger()),
-                            )
+                            ui.label(theme::Role::Caption.rich("empty").color(theme::danger()))
                             .on_hover_text(
                                 "The share reports no content for this file; it cannot be played.",
                             );
@@ -459,8 +560,8 @@ fn episode_row(
                     }
                     if let Some(at) = episode.resume_at() {
                         ui.label(
-                            egui::RichText::new(format!("resume {}", ui::format_time(at)))
-                                .size(12.0)
+                            theme::Role::Caption
+                                .rich(format!("resume {}", ui::format_time(at)))
                                 .color(theme::accent()),
                         );
                     }

crates/pstr-app/src/ui/transport.rs

@@ -116,7 +116,7 @@ pub fn mini(
         // one-way trip: playback carries on with nowhere to watch it.
         if ui
             .add(
-                egui::Button::new(egui::RichText::new("Back to video").size(13.0))
+                egui::Button::new(theme::Role::Label.rich("Back to video"))
                     .fill(theme::card_hover())
                     .corner_radius(CornerRadius::same(8)),
             )
@@ -132,12 +132,8 @@ pub fn mini(
             // is the only thing that still knows which title this came from.
             if ui
                 .add(
-                    egui::Label::new(
-                        egui::RichText::new(&playback.target.title_name)
-                            .size(14.0)
-                            .strong(),
-                    )
-                    .sense(Sense::click()),
+                    egui::Label::new(theme::Role::Body.rich(&playback.target.title_name).strong())
+                        .sense(Sense::click()),
                 )
                 .on_hover_text("Show this title")
                 .clicked()
@@ -287,7 +283,7 @@ fn step_button(
 ) {
     let response = ui.add_enabled(
         enabled,
-        egui::Button::new(egui::RichText::new(label).size(15.0)).min_size(Vec2::new(38.0, 30.0)),
+        egui::Button::new(theme::Role::Subhead.rich(label)).min_size(Vec2::new(38.0, 30.0)),
     );
     if response.on_hover_text(hover).clicked() {
         push(actions);

crates/pstr-core/src/appearance.rs

@@ -9,7 +9,8 @@
 use crate::config::{AppDirs, read_json, write_json};
 use crate::error::Result;
 
-/// A palette family: Catppuccin's four, plus the one this app shipped with.
+/// A palette family: Catppuccin's four, the one this app shipped with, and one
+/// borrowed from a menu screen.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
 #[serde(rename_all = "kebab-case")]
 pub enum Flavor {
@@ -22,15 +23,18 @@ pub enum Flavor {
     Frappe,
     Macchiato,
     Mocha,
+    /// Black, white and one loud red — the Persona 5 menus.
+    Persona5,
 }
 
 impl Flavor {
-    pub const ALL: [Self; 5] = [
+    pub const ALL: [Self; 6] = [
         Self::Proton,
         Self::Mocha,
         Self::Macchiato,
         Self::Frappe,
         Self::Latte,
+        Self::Persona5,
     ];
 
     pub fn label(self) -> &'static str {
@@ -40,6 +44,7 @@ impl Flavor {
             Self::Frappe => "Catppuccin Frappé",
             Self::Macchiato => "Catppuccin Macchiato",
             Self::Mocha => "Catppuccin Mocha",
+            Self::Persona5 => "Persona 5",
         }
     }
 
@@ -50,6 +55,7 @@ impl Flavor {
             Self::Frappe => "Dark, warm, the lowest contrast of the three",
             Self::Macchiato => "Dark, between Frappé and Mocha",
             Self::Mocha => "Dark, the deepest of Catppuccin's three",
+            Self::Persona5 => "Black and white with one loud red — pick the Red accent for it",
         }
     }
 
@@ -82,10 +88,15 @@ pub enum Accent {
     Blue,
     Teal,
     Peach,
+    /// The flavour's warning colour, used on purpose. Every flavour has one
+    /// because everything here needs a colour for a failure, and in
+    /// [`Flavor::Persona5`] it is the point of the palette rather than an
+    /// afterthought.
+    Red,
 }
 
 impl Accent {
-    pub const ALL: [Self; 8] = [
+    pub const ALL: [Self; 9] = [
         Self::Mauve,
         Self::Pink,
         Self::Sky,
@@ -94,6 +105,7 @@ impl Accent {
         Self::Blue,
         Self::Teal,
         Self::Peach,
+        Self::Red,
     ];
 
     pub fn label(self) -> &'static str {
@@ -106,6 +118,7 @@ impl Accent {
             Self::Blue => "Blue",
             Self::Teal => "Teal",
             Self::Peach => "Peach",
+            Self::Red => "Red",
         }
     }
 }
@@ -151,6 +164,427 @@ pub fn save(dirs: &AppDirs, appearance: &Appearance) -> Result<()> {
     write_json(&appearance_file(dirs), appearance)
 }
 
+/// One colour, 8 bits a channel, with no alpha.
+///
+/// Deliberately not a front end's colour type: this module resolves a choice
+/// into colours for *both* clients, and neither egui's `Color32` nor Compose's
+/// `Color` may appear here.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Rgb {
+    pub r: u8,
+    pub g: u8,
+    pub b: u8,
+}
+
+impl Rgb {
+    pub const BLACK: Self = Self::new(0, 0, 0);
+
+    pub const fn new(r: u8, g: u8, b: u8) -> Self {
+        Self { r, g, b }
+    }
+
+    /// Packed as `0xAARRGGBB`, opaque — the form both Android and a hex literal
+    /// want.
+    pub const fn argb(self) -> u32 {
+        0xff00_0000 | ((self.r as u32) << 16) | ((self.g as u32) << 8) | self.b as u32
+    }
+}
+
+/// One channel from sRGB into linear light, as the sRGB transfer function
+/// defines it. Blending has to happen here: mixing sRGB values directly darkens
+/// the middle of a ramp between saturated hues, which is exactly where a
+/// gradient is looked at.
+fn linear(channel: u8) -> f32 {
+    let value = channel as f32 / 255.0;
+    if value <= 0.04045 {
+        value / 12.92
+    } else {
+        ((value + 0.055) / 1.055).powf(2.4)
+    }
+}
+
+/// Back out of linear light, rounded to a channel.
+fn gamma(value: f32) -> u8 {
+    let value = value.clamp(0.0, 1.0);
+    let encoded = if value <= 0.003_130_8 {
+        value * 12.92
+    } else {
+        1.055 * value.powf(1.0 / 2.4) - 0.055
+    };
+    (encoded * 255.0).round().clamp(0.0, 255.0) as u8
+}
+
+/// Blend two colours in linear light.
+pub fn mix(from: Rgb, to: Rgb, t: f32) -> Rgb {
+    let blend = |from: u8, to: u8| gamma(linear(from) * (1.0 - t) + linear(to) * t);
+    Rgb::new(
+        blend(from.r, to.r),
+        blend(from.g, to.g),
+        blend(from.b, to.b),
+    )
+}
+
+/// Relative luminance, in linear light, as WCAG defines it.
+pub fn luminance(color: Rgb) -> f32 {
+    0.2126 * linear(color.r) + 0.7152 * linear(color.g) + 0.0722 * linear(color.b)
+}
+
+/// WCAG contrast between two opaque colours: 1.0 for a colour against itself,
+/// 21.0 for black against white.
+fn contrast(one: Rgb, other: Rgb) -> f32 {
+    let (one, other) = (luminance(one), luminance(other));
+    (one.max(other) + 0.05) / (one.min(other) + 0.05)
+}
+
+/// The least contrast a label gets anywhere along a gradient between two
+/// colours. Sampled rather than solved: the worst point is not always an end,
+/// because the ink can be brighter than one end and darker than the other.
+pub fn worst_contrast(from: Rgb, to: Rgb, ink: Rgb) -> f32 {
+    (0..=4)
+        .map(|step| contrast(mix(from, to, step as f32 / 4.0), ink))
+        .fold(f32::INFINITY, f32::min)
+}
+
+/// The least contrast the app will accept between a label and the fill under
+/// it: WCAG AA for large text, which is what wears the accent — button labels,
+/// a tab, a play glyph, never body copy.
+pub const MIN_CONTRAST: f32 = 3.0;
+
+/// Every colour a client draws with, resolved from a [`Flavor`] and an
+/// [`Accent`].
+///
+/// `Copy`, and small, so reading it is a lock and a memcpy rather than anything
+/// a drawing loop has to think about.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Palette {
+    /// Behind everything: the page.
+    pub background: Rgb,
+    /// The bars above and below it.
+    pub surface: Rgb,
+    /// The deepest colour in the flavour — text fields, wells.
+    pub sunken: Rgb,
+    /// Tiles, rows, forms.
+    pub card: Rgb,
+    pub card_hover: Rgb,
+    pub border: Rgb,
+    pub text: Rgb,
+    pub muted: Rgb,
+    /// The one strong colour.
+    pub accent: Rgb,
+    /// What a gradient in the accent runs into. Equal to [`Self::accent`] when
+    /// the accent is a single hue and gradients would have nothing to do.
+    pub accent_alt: Rgb,
+    /// The accent taken down into the background, for a pressed control and for
+    /// selection behind text.
+    pub accent_dim: Rgb,
+    /// Ink that stays readable on top of the accent. Chosen by the accent's
+    /// luminance, because Catppuccin's dark flavours have *pale* accents and
+    /// white-on-pastel is not readable at 13 px.
+    pub on_accent: Rgb,
+    pub danger: Rgb,
+    /// Whether this is a light theme.
+    pub light: bool,
+}
+
+/// One flavour's raw colours, named as Catppuccin names them.
+///
+/// Stored rather than computed: these are somebody else's palette, and the
+/// point of using it is to use it exactly.
+#[derive(Clone, Copy)]
+struct Ramp {
+    base: Rgb,
+    mantle: Rgb,
+    crust: Rgb,
+    surface0: Rgb,
+    surface1: Rgb,
+    subtext0: Rgb,
+    text: Rgb,
+    pink: Rgb,
+    mauve: Rgb,
+    sky: Rgb,
+    sapphire: Rgb,
+    blue: Rgb,
+    lavender: Rgb,
+    teal: Rgb,
+    green: Rgb,
+    peach: Rgb,
+    yellow: Rgb,
+    red: Rgb,
+    light: bool,
+}
+
+const fn rgb(hex: u32) -> Rgb {
+    Rgb::new(
+        ((hex >> 16) & 0xff) as u8,
+        ((hex >> 8) & 0xff) as u8,
+        (hex & 0xff) as u8,
+    )
+}
+
+/// The palette this app shipped with, extended to the hues an accent can be.
+///
+/// Only `mauve` — Proton purple — and `red` are from the original; the rest are
+/// chosen to sit on a near-black base at roughly the saturation that one does,
+/// which is a good deal hotter than any Catppuccin flavour.
+const PROTON: Ramp = Ramp {
+    base: rgb(0x0e0e12),
+    mantle: rgb(0x17171d),
+    crust: rgb(0x0a0a0d),
+    surface0: rgb(0x1e1e26),
+    surface1: rgb(0x2a2a35),
+    subtext0: rgb(0x8e8e9c),
+    text: rgb(0xeaeaf0),
+    pink: rgb(0xff5fbe),
+    mauve: rgb(0x7d4dff),
+    sky: rgb(0x4dd2ff),
+    sapphire: rgb(0x3a8fc4),
+    blue: rgb(0x3f6fe0),
+    lavender: rgb(0xa68cff),
+    teal: rgb(0x3fd6b8),
+    green: rgb(0x56d364),
+    peach: rgb(0xff9a4d),
+    yellow: rgb(0xffd166),
+    red: rgb(0xe05561),
+    light: false,
+};
+
+const LATTE: Ramp = Ramp {
+    base: rgb(0xeff1f5),
+    mantle: rgb(0xe6e9ef),
+    crust: rgb(0xdce0e8),
+    surface0: rgb(0xccd0da),
+    surface1: rgb(0xbcc0cc),
+    subtext0: rgb(0x6c6f85),
+    text: rgb(0x4c4f69),
+    pink: rgb(0xea76cb),
+    mauve: rgb(0x8839ef),
+    sky: rgb(0x04a5e5),
+    sapphire: rgb(0x209fb5),
+    blue: rgb(0x1e66f5),
+    lavender: rgb(0x7287fd),
+    teal: rgb(0x179299),
+    green: rgb(0x40a02b),
+    peach: rgb(0xfe640b),
+    yellow: rgb(0xdf8e1d),
+    red: rgb(0xd20f39),
+    light: true,
+};
+
+const FRAPPE: Ramp = Ramp {
+    base: rgb(0x303446),
+    mantle: rgb(0x292c3c),
+    crust: rgb(0x232634),
+    surface0: rgb(0x414559),
+    surface1: rgb(0x51576d),
+    subtext0: rgb(0xa5adce),
+    text: rgb(0xc6d0f5),
+    pink: rgb(0xf4b8e4),
+    mauve: rgb(0xca9ee6),
+    sky: rgb(0x99d1db),
+    sapphire: rgb(0x85c1dc),
+    blue: rgb(0x8caaee),
+    lavender: rgb(0xbabbf1),
+    teal: rgb(0x81c8be),
+    green: rgb(0xa6d189),
+    peach: rgb(0xef9f76),
+    yellow: rgb(0xe5c890),
+    red: rgb(0xe78284),
+    light: false,
+};
+
+const MACCHIATO: Ramp = Ramp {
+    base: rgb(0x24273a),
+    mantle: rgb(0x1e2030),
+    crust: rgb(0x181926),
+    surface0: rgb(0x363a4f),
+    surface1: rgb(0x494d64),
+    subtext0: rgb(0xa5adcb),
+    text: rgb(0xcad3f5),
+    pink: rgb(0xf5bde6),
+    mauve: rgb(0xc6a0f6),
+    sky: rgb(0x91d7e3),
+    sapphire: rgb(0x7dc4e4),
+    blue: rgb(0x8aadf4),
+    lavender: rgb(0xb7bdf8),
+    teal: rgb(0x8bd5ca),
+    green: rgb(0xa6da95),
+    peach: rgb(0xf5a97f),
+    yellow: rgb(0xeed49f),
+    red: rgb(0xed8796),
+    light: false,
+};
+
+const MOCHA: Ramp = Ramp {
+    base: rgb(0x1e1e2e),
+    mantle: rgb(0x181825),
+    crust: rgb(0x11111b),
+    surface0: rgb(0x313244),
+    surface1: rgb(0x45475a),
+    subtext0: rgb(0xa6adc8),
+    text: rgb(0xcdd6f4),
+    pink: rgb(0xf5c2e7),
+    mauve: rgb(0xcba6f7),
+    sky: rgb(0x89dceb),
+    sapphire: rgb(0x74c7ec),
+    blue: rgb(0x89b4fa),
+    lavender: rgb(0xb4befe),
+    teal: rgb(0x94e2d5),
+    green: rgb(0xa6e3a1),
+    peach: rgb(0xfab387),
+    yellow: rgb(0xf9e2af),
+    red: rgb(0xf38ba8),
+    light: false,
+};
+
+/// Persona 5's menus: black, white, and a red that is not asking permission.
+///
+/// The three colours that matter are `crust`/`base` (black), `text` (white) and
+/// `red` — everything between them is that same red bled into the black, which
+/// is what keeps a card from reading as grey furniture in a palette that has no
+/// grey in it. The other hues exist because an accent can be any of them; they
+/// are pushed to full saturation to sit on a black page, which is the one thing
+/// this palette has in common with [`PROTON`].
+const PERSONA5: Ramp = Ramp {
+    base: rgb(0x0a0708),
+    mantle: rgb(0x140d0f),
+    crust: rgb(0x000000),
+    surface0: rgb(0x1d1215),
+    surface1: rgb(0x33191d),
+    subtext0: rgb(0xb59a9d),
+    text: rgb(0xf5f2f2),
+    pink: rgb(0xff2e63),
+    mauve: rgb(0xb13bd6),
+    sky: rgb(0x2ec7ff),
+    sapphire: rgb(0x1f9bd0),
+    blue: rgb(0x2f5ee0),
+    lavender: rgb(0xa07bff),
+    teal: rgb(0x12c2a0),
+    green: rgb(0x2fbf4f),
+    peach: rgb(0xff7a1a),
+    yellow: rgb(0xffc400),
+    red: rgb(0xe60012),
+    light: false,
+};
+
+impl Ramp {
+    const fn of(flavor: Flavor) -> Self {
+        match flavor {
+            Flavor::Proton => PROTON,
+            Flavor::Latte => LATTE,
+            Flavor::Frappe => FRAPPE,
+            Flavor::Macchiato => MACCHIATO,
+            Flavor::Mocha => MOCHA,
+            Flavor::Persona5 => PERSONA5,
+        }
+    }
+
+    /// The accent, and the hue a gradient in it runs into.
+    ///
+    /// The partners are neighbours on the wheel rather than complements: a
+    /// gradient across half the spectrum passes through a colour that belongs
+    /// to neither end, and on a seek bar that reads as a bug. The exception is
+    /// [`Accent::PinkSky`], which is the whole point of that entry.
+    const fn accents(&self, accent: Accent) -> (Rgb, Rgb) {
+        match accent {
+            Accent::Mauve => (self.mauve, self.blue),
+            Accent::Pink => (self.pink, self.mauve),
+            Accent::Sky => (self.sky, self.sapphire),
+            Accent::PinkSky => (self.pink, self.sky),
+            Accent::Lavender => (self.lavender, self.blue),
+            Accent::Blue => (self.blue, self.sapphire),
+            Accent::Teal => (self.teal, self.green),
+            Accent::Peach => (self.peach, self.yellow),
+            Accent::Red => (self.red, self.pink),
+        }
+    }
+}
+
+impl Palette {
+    /// The default, spelled out as a constant so the global has something to
+    /// hold before [`apply`] first runs — a `Ui` built during startup, or a
+    /// panic message painted before the engine exists, still gets colours.
+    pub const PROTON: Self = Self {
+        background: PROTON.base,
+        surface: PROTON.mantle,
+        sunken: PROTON.crust,
+        card: PROTON.surface0,
+        card_hover: PROTON.surface1,
+        border: rgb(0x262630),
+        text: PROTON.text,
+        muted: PROTON.subtext0,
+        accent: PROTON.mauve,
+        accent_alt: PROTON.blue,
+        accent_dim: rgb(0x5333ad),
+        on_accent: PROTON.text,
+        danger: PROTON.red,
+        light: false,
+    };
+
+    /// Resolve a choice into colours.
+    pub fn resolve(appearance: Appearance) -> Self {
+        let ramp = Ramp::of(appearance.flavor);
+        let (accent, partner) = ramp.accents(appearance.accent);
+        // Catppuccin's Latte accents are tuned to be *read*, on a light page,
+        // at body-text weight — which makes them mid-luminance, and a
+        // mid-luminance fill is one that neither black nor white sits on. They
+        // are taken down in value here, and only here: the hue and the
+        // saturation are Latte's, so it still looks like Latte, and a label on
+        // a button is legible.
+        let deepen = |color: Rgb| {
+            if ramp.light {
+                mix(color, Rgb::BLACK, 0.30)
+            } else {
+                color
+            }
+        };
+        let accent = deepen(accent);
+        let accent_alt = if appearance.gradients {
+            deepen(partner)
+        } else {
+            accent
+        };
+
+        // Ink that survives on the accent. The flavour's own reading first —
+        // pale text on a dark theme — and the opposite when that does not clear
+        // the bar, which on Catppuccin's dark flavours is most of the time:
+        // their accents are *pastel*, and white on #f5c2e7 is not a label.
+        //
+        // Latte's darkest colour is its body text, and even that is only #4c4f69,
+        // so the dark side is taken a third of the way to black.
+        let ink_dark = if ramp.light {
+            mix(ramp.text, Rgb::BLACK, 0.35)
+        } else {
+            ramp.crust
+        };
+        let ink_light = if ramp.light { ramp.base } else { ramp.text };
+        let on_accent = if worst_contrast(accent, accent_alt, ink_light) >= MIN_CONTRAST {
+            ink_light
+        } else {
+            ink_dark
+        };
+
+        Self {
+            background: ramp.base,
+            surface: ramp.mantle,
+            sunken: ramp.crust,
+            card: ramp.surface0,
+            card_hover: ramp.surface1,
+            border: ramp.surface1,
+            text: ramp.text,
+            muted: ramp.subtext0,
+            accent,
+            accent_alt,
+            // Behind text, so it is the accent taken most of the way back to
+            // the page: a selection in a saturated hue is a selection nobody
+            // can read through.
+            accent_dim: mix(accent, ramp.base, if ramp.light { 0.55 } else { 0.45 }),
+            on_accent,
+            danger: ramp.red,
+            light: ramp.light,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -209,4 +643,84 @@ mod tests {
             assert_eq!(flavor.is_light(), flavor == Flavor::Latte);
         }
     }
+
+    #[test]
+    fn every_flavour_and_accent_resolves_to_readable_ink() {
+        for flavor in Flavor::ALL {
+            for accent in Accent::ALL {
+                let palette = Palette::resolve(Appearance {
+                    flavor,
+                    accent,
+                    gradients: true,
+                });
+                let ratio = worst_contrast(palette.accent, palette.accent_alt, palette.on_accent);
+                assert!(
+                    ratio >= MIN_CONTRAST,
+                    "{flavor:?}/{accent:?}: contrast {ratio:.2}",
+                );
+            }
+        }
+    }
+
+    #[test]
+    fn only_the_light_flavour_reports_itself_light() {
+        for flavor in Flavor::ALL {
+            let palette = Palette::resolve(Appearance {
+                flavor,
+                ..Appearance::default()
+            });
+            assert_eq!(palette.light, flavor.is_light());
+            // And the page is on the right side of the middle either way.
+            assert_eq!(luminance(palette.background) > 0.5, flavor.is_light());
+        }
+    }
+
+    #[test]
+    fn persona_5_is_black_with_that_red_in_it() {
+        let palette = Palette::resolve(Appearance {
+            flavor: Flavor::Persona5,
+            accent: Accent::Red,
+            gradients: false,
+        });
+        assert_eq!(palette.accent, PERSONA5.red);
+        assert!(!palette.light);
+        // Black enough that the artwork is the brightest thing on the page:
+        // darker than the palette this app shipped with, which is the other
+        // near-black one.
+        assert!(luminance(palette.background) < luminance(PROTON.base));
+    }
+
+    #[test]
+    fn every_flavour_can_wear_its_own_warning_colour() {
+        for flavor in Flavor::ALL {
+            let palette = Palette::resolve(Appearance {
+                flavor,
+                accent: Accent::Red,
+                gradients: true,
+            });
+            // The accent is the flavour's red — deepened on the light flavour,
+            // where it would otherwise be too bright to put a label on.
+            assert!(palette.accent.r > palette.accent.b, "{flavor:?}");
+            assert_ne!(palette.accent, palette.background, "{flavor:?}");
+        }
+    }
+
+    #[test]
+    fn turning_gradients_off_leaves_one_colour_to_draw() {
+        let flat = Palette::resolve(Appearance {
+            accent: Accent::PinkSky,
+            gradients: false,
+            ..Appearance::default()
+        });
+        assert_eq!(flat.accent, flat.accent_alt);
+    }
+
+    #[test]
+    fn a_blend_stays_between_the_two_colours_it_blends() {
+        let (from, to) = (Rgb::new(0, 0, 0), Rgb::new(255, 255, 255));
+        assert_eq!(mix(from, to, 0.0), from);
+        assert_eq!(mix(from, to, 1.0), to);
+        assert!(luminance(mix(from, to, 0.5)) > luminance(from));
+        assert!(luminance(mix(from, to, 0.5)) < luminance(to));
+    }
 }

crates/pstr-core/src/catalog.rs

@@ -227,6 +227,16 @@ impl Catalog {
         Ok(catalog)
     }
 
+    /// How many rows this connection has written since it was opened.
+    ///
+    /// A cache key, not a statistic: anything derived from the catalog stays
+    /// valid exactly as long as this does not move. SQLite counts it for us, so
+    /// no write path has to remember to invalidate anything — which is the
+    /// failure mode a hand-maintained counter has.
+    pub fn writes(&self) -> u64 {
+        self.conn.total_changes()
+    }
+
     fn migrate(&mut self) -> Result<()> {
         let version: i64 = self
             .conn
@@ -983,7 +993,7 @@ pub fn build_rows(share_id: &str, nodes: &[proton_drive_rs::Node]) -> Vec<Catalo
                 // episode's name rather than the series'.
                 if row.parsed.episode_title.is_none()
                     && !row.parsed.title.is_empty()
-                    && row.parsed.title != title
+                    && !row.parsed.title.eq_ignore_ascii_case(&title)
                 {
                     let rest = strip_prefix_title(&row.parsed.title, &title);
                     // …unless what is left is a season marker. `Oshi no Ko 3rd
@@ -992,7 +1002,11 @@ pub fn build_rows(share_id: &str, nodes: &[proton_drive_rs::Node]) -> Vec<Catalo
                     // that is worse than calling none of them anything.
                     if naming::is_season_marker(&rest) {
                         row.parsed.season = row.parsed.season.or(naming::parse(&rest).season);
-                    } else {
+                    } else if !rest.eq_ignore_ascii_case(&title) {
+                        // Nor when the strip found nothing to remove: a filename
+                        // whose title only *differs* from the folder's — spacing,
+                        // punctuation, a stray article — names the series, not the
+                        // episode, and taking it hands every row the same text.
                         row.parsed.episode_title = Some(rest);
                     }
                 }
@@ -1076,10 +1090,17 @@ fn ancestry(
 ///
 /// `Neon Genesis Evangelion - Death & Rebirth` under a folder called
 /// `Neon Genesis Evangelion` should read as `Death & Rebirth`.
+///
+/// Case-insensitively, because the two names come from different places: the
+/// folder is typed by whoever organised the share and the prefix is whatever a
+/// release group capitalised. `[Anime Time] Attack On Titan - 38.mkv` under a
+/// folder called `Attack on Titan` differs in exactly one letter, and a
+/// case-sensitive strip leaves the whole series name behind as the episode's.
 fn strip_prefix_title(episode: &str, series: &str) -> String {
     let stripped = episode
-        .strip_prefix(series)
-        .map(|rest| rest.trim_start_matches([' ', '-', '_', '.', ':']))
+        .get(..series.len())
+        .filter(|head| head.eq_ignore_ascii_case(series))
+        .map(|_| episode[series.len()..].trim_start_matches([' ', '-', '_', '.', ':']))
         .unwrap_or(episode)
         .trim();
 
@@ -1632,6 +1653,47 @@ mod tests {
         assert_eq!(episode.parsed.episode_title, None);
     }
 
+    /// **What every episode of Attack on Titan was called.** The folder and the
+    /// release group capitalised the same series two ways, and a case-sensitive
+    /// prefix strip left the whole series name behind — so all fifty-nine rows
+    /// read `Attack On Titan`, naming nothing and telling the viewer apart from
+    /// nothing.
+    #[test]
+    fn a_series_name_cased_differently_is_not_the_episodes_name() {
+        let nodes = vec![
+            root(),
+            folder("aot", Some("root"), "Attack on Titan"),
+            video("e38", "aot", "[Anime Time] Attack On Titan - 38.mkv"),
+        ];
+        let rows = build_rows("share", &nodes);
+        let episode = row(&rows, "e38");
+
+        assert_eq!(episode.parsed.title, "Attack on Titan", "the folder's");
+        assert_eq!(episode.parsed.episode, Some(38));
+        assert_eq!(episode.parsed.episode_title, None);
+    }
+
+    /// The prefix strip is case-insensitive for the same reason: what follows
+    /// the series name is the episode's, however the group capitalised it.
+    #[test]
+    fn a_prefix_cased_differently_is_still_stripped() {
+        let nodes = vec![
+            root(),
+            folder("eva", Some("root"), "Neon Genesis Evangelion"),
+            video(
+                "film",
+                "eva",
+                "NEON GENESIS EVANGELION - Death & Rebirth.mkv",
+            ),
+        ];
+        let rows = build_rows("share", &nodes);
+
+        assert_eq!(
+            row(&rows, "film").parsed.episode_title.as_deref(),
+            Some("Death & Rebirth"),
+        );
+    }
+
     /// The deepest naming folder wins, so films inside a collection folder are
     /// titled individually rather than by the collection.
     #[test]

crates/pstr-core/src/chapters.rs

@@ -0,0 +1,483 @@
+//! The chapters a file was muxed with, and what they are for.
+//!
+//! Anime releases mark their opening and ending as chapters, which is the whole
+//! reason this exists: with them a player can offer to skip the ninety seconds
+//! everyone skips, and without them it cannot.
+//!
+//! Nothing here talks to a player. Reading the chapter list out of mpv is
+//! `pstr-player`'s job on the desktop and the JNI adapter's on Android; both
+//! hand the result to [`roles`], so a chapter means the same thing on either.
+
+/// One chapter of the file.
+#[derive(Debug, Clone, PartialEq)]
+pub struct Chapter {
+    /// Position in the list, which is what mpv's `chapter` property is set to.
+    pub index: i64,
+    /// The name the muxer gave it, if any.
+    pub title: Option<String>,
+    /// Where it starts, in seconds.
+    pub start: f64,
+}
+
+impl Chapter {
+    /// What to show in a list. A nameless chapter is still worth an entry —
+    /// it is a place in the file — so it gets its number.
+    pub fn label(&self) -> String {
+        match &self.title {
+            Some(title) => title.clone(),
+            None => format!("Chapter {}", self.index + 1),
+        }
+    }
+
+    /// What this chapter is, from its name alone.
+    ///
+    /// Prefer [`roles`], which resolves the names that only mean one thing *in
+    /// context* — a chapter called `Intro` is an opening in one release and the
+    /// first ten minutes of the story in another.
+    pub fn role(&self) -> ChapterRole {
+        match Claim::of(self.title.as_deref().unwrap_or_default()) {
+            Claim::Opening => ChapterRole::Opening,
+            Claim::Ending => ChapterRole::Ending,
+            Claim::Preview => ChapterRole::Preview,
+            // Unresolved without the rest of the file: assume it is content,
+            // which is the reading that never skips anything.
+            _ => ChapterRole::Content,
+        }
+    }
+}
+
+/// The kinds of chapter worth treating differently from "part of the episode".
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ChapterRole {
+    /// The opening titles.
+    Opening,
+    /// The ending titles.
+    Ending,
+    /// A preview of the next episode, after the ending.
+    Preview,
+    /// Anything else, including everything unnamed.
+    Content,
+}
+
+impl ChapterRole {
+    /// What a button offering to skip this should say. `None` for a chapter
+    /// nobody wants skipped.
+    pub fn skip_label(self) -> Option<&'static str> {
+        match self {
+            Self::Opening => Some("Skip opening"),
+            Self::Ending => Some("Skip ending"),
+            Self::Preview => Some("Skip preview"),
+            Self::Content => None,
+        }
+    }
+
+    /// Whether this is something the file could end on without the viewer
+    /// missing anything: credits and a trailer for next week.
+    ///
+    /// An *opening* is not, even though it is skippable — a file does not end
+    /// with one, and treating it as tail would make a mis-tagged chapter
+    /// auto-advance out of the episode.
+    pub fn ends_the_episode(self) -> bool {
+        matches!(self, Self::Ending | Self::Preview)
+    }
+}
+
+/// What a chapter's *name* claims, before the rest of the file is consulted.
+///
+/// The two `Maybe` variants are the whole reason this is separate from
+/// [`ChapterRole`]. `Intro` is the opening in one release and, in the first
+/// episode of Oshi no Ko, a ten-minute introduction to the series that a viewer
+/// must not be skipped out of. `Credits` and `Cast` are the ending in most
+/// files and a mid-episode scene in a few. Neither can be settled by the name.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Claim {
+    Opening,
+    Ending,
+    Preview,
+    /// Reads like an opening, but only if the file has no real one and it is
+    /// the length of a theme song.
+    MaybeOpening,
+    /// Reads like credits, but only near the end of the file or at theme
+    /// length.
+    MaybeEnding,
+    Content,
+}
+
+/// How long an opening or ending theme runs.
+///
+/// Anime themes are ninety seconds by convention and rarely stray far. This is
+/// the corroboration for a name that could go either way: a chapter called
+/// `Intro` that runs eleven minutes is not a theme song, whatever it is called.
+const THEME_SECONDS: std::ops::RangeInclusive<f64> = 45.0..=150.0;
+
+/// Credits can run longer than a theme — a full cast roll over a still — so a
+/// chapter that only *reads* like an ending gets this much room when it sits at
+/// the end of the file.
+const CREDITS_SECONDS: std::ops::RangeInclusive<f64> = 30.0..=300.0;
+
+/// An opening that far into the file is not an opening. Cold opens run long in
+/// a first episode, so this is generous.
+const OPENING_BEFORE_SECONDS: f64 = 480.0;
+
+/// Where the last part of a file starts, as a fraction of it. A chapter that
+/// merely reads like credits is taken as credits past this point.
+const TAIL_FRACTION: f64 = 0.75;
+
+impl Claim {
+    /// Read a claim out of a chapter name.
+    ///
+    /// Matched on whole words from the front, not on substrings: `Operation
+    /// Briefing` starts with `op` and is not an opening, `Ending Note` is not
+    /// an ending, and skipping a viewer out of either is a mistake they cannot
+    /// undo without finding the seek bar. Leading numbering (`01 - OP`, `1.
+    /// Opening`) is stepped over first, because plenty of muxes carry it.
+    fn of(title: &str) -> Self {
+        // Japanese names appear verbatim in releases from JP sources, and they
+        // are unambiguous where the English ones are not. Checked before the
+        // word split, which only knows about ASCII and would find no words at
+        // all in a name written entirely in kana.
+        if title.contains("オープニング") {
+            return Self::Opening;
+        }
+        if title.contains("エンディング") {
+            return Self::Ending;
+        }
+        if title.contains("予告") {
+            return Self::Preview;
+        }
+
+        let words = words(title);
+        let words: Vec<&str> = words.iter().map(String::as_str).collect();
+        let Some((head, rest)) = words.split_first() else {
+            return Self::Content;
+        };
+        let second = rest.first().copied().unwrap_or_default();
+
+        match (*head, second) {
+            // Two-word forms first: the second word is what tells `next
+            // episode` from `next`, and `end credits` from `end`.
+            ("next", _) | ("nep", _) => Self::Preview,
+            ("end" | "ending" | "closing", "credits") => Self::Ending,
+            ("cast" | "staff", "roll" | "credits") => Self::Ending,
+            ("opening" | "op", "theme" | "song" | "credits") => Self::Opening,
+            ("ending" | "ed", "theme" | "song") => Self::Ending,
+
+            ("op" | "opening" | "openning" | "ncop", _) => Self::Opening,
+            ("ed" | "ending" | "nced" | "outro" | "endcard", _) => Self::Ending,
+            ("preview" | "pv" | "trailer" | "teaser" | "yokoku", _) => Self::Preview,
+
+            ("intro", _) => Self::MaybeOpening,
+            ("credits" | "closing" | "cast" | "staff", _) => Self::MaybeEnding,
+            _ => Self::Content,
+        }
+    }
+}
+
+/// A chapter name as lowercase words, with any leading numbering dropped.
+///
+/// `OP1` and `ED2` keep their tag and lose their number — the digit is part of
+/// the tag, not a word — while `02 - Opening` loses its leading `02` entirely.
+fn words(title: &str) -> Vec<String> {
+    let mut words: Vec<String> = title
+        .trim()
+        .to_ascii_lowercase()
+        .split(|c: char| !c.is_ascii_alphanumeric())
+        .filter(|word| !word.is_empty())
+        .map(|word| {
+            word.trim_end_matches(|c: char| c.is_ascii_digit())
+                .to_string()
+        })
+        .collect();
+    // A leading token that was *only* digits is numbering, not a name.
+    if words.first().is_some_and(String::is_empty) {
+        words.remove(0);
+    }
+    words.retain(|word| !word.is_empty());
+    words
+}
+
+/// The role of every chapter in a file, with the file's own shape taken into
+/// account.
+///
+/// This is the function to use. [`Chapter::role`] reads a name in isolation and
+/// cannot tell an opening called `Intro` from ten minutes of story called the
+/// same thing; here the other chapters and the running time settle it:
+///
+/// * a chapter that merely *reads* like an opening is one only when the file
+///   has no chapter that says so outright, it runs the length of a theme song,
+///   and it is near the front;
+/// * a chapter that reads like credits is the ending when it runs to about that
+///   length, or when it sits in the last quarter of the file.
+///
+/// Both rules fail *towards content*: not offering a skip costs a button, and
+/// skipping the viewer out of the story costs them the story.
+pub fn roles(chapters: &[Chapter], duration: Option<f64>) -> Vec<ChapterRole> {
+    let claims: Vec<Claim> = chapters
+        .iter()
+        .map(|chapter| Claim::of(chapter.title.as_deref().unwrap_or_default()))
+        .collect();
+    let has_real_opening = claims.contains(&Claim::Opening);
+
+    claims
+        .iter()
+        .enumerate()
+        .map(|(index, claim)| {
+            let length = chapter_end(chapters, index, duration)
+                .map(|end| end - chapters[index].start)
+                .filter(|length| *length > 0.0);
+            let start = chapters[index].start;
+
+            match claim {
+                Claim::Opening => ChapterRole::Opening,
+                Claim::Ending => ChapterRole::Ending,
+                Claim::Preview => ChapterRole::Preview,
+                Claim::MaybeOpening
+                    if !has_real_opening
+                        && start <= OPENING_BEFORE_SECONDS
+                        && length.is_some_and(|length| THEME_SECONDS.contains(&length)) =>
+                {
+                    ChapterRole::Opening
+                }
+                Claim::MaybeEnding
+                    if length.is_some_and(|length| CREDITS_SECONDS.contains(&length))
+                        || duration.is_some_and(|total| start >= total * TAIL_FRACTION) =>
+                {
+                    ChapterRole::Ending
+                }
+                _ => ChapterRole::Content,
+            }
+        })
+        .collect()
+}
+
+/// Where the run of chapters that ends the file — credits, a preview, and
+/// nothing the viewer would miss — begins.
+///
+/// **The suffix, not the last chapter.** A release that puts a Part C after the
+/// ending and a preview after that (Fullmetal Alchemist Brotherhood does,
+/// exactly once) must give up only the preview, or auto-advancing skips a scene
+/// that matters. Walking back from the end and stopping at the first chapter
+/// that is content is what expresses that: `… ED · Part C · Preview` yields the
+/// preview alone, while the ordinary `… ED · Preview` yields both.
+///
+/// `None` when the file ends on content, has no chapters, or is *entirely*
+/// skippable — the last of which is a mis-tagged file, not an episode that is
+/// all credits.
+pub fn credits_start(chapters: &[Chapter], roles: &[ChapterRole]) -> Option<f64> {
+    let first = roles
+        .iter()
+        .rposition(|role| !role.ends_the_episode())
+        .map(|last_content| last_content + 1)?;
+    if first >= chapters.len() {
+        return None;
+    }
+    Some(chapters[first].start)
+}
+
+/// Where the chapter starting at `index` ends: the next one's start, or the end
+/// of the file.
+pub fn chapter_end(chapters: &[Chapter], index: usize, duration: Option<f64>) -> Option<f64> {
+    chapters
+        .get(index + 1)
+        .map(|next| next.start)
+        .or(duration)
+        .filter(|end| *end > 0.0)
+}
+
+/// The chapter a position falls in.
+///
+/// Linear rather than a binary search: a file has a dozen chapters, and this is
+/// called once a frame at most.
+pub fn chapter_at(chapters: &[Chapter], position: f64) -> Option<usize> {
+    chapters
+        .iter()
+        .rposition(|chapter| position + f64::EPSILON >= chapter.start)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn chapter(index: i64, title: &str, start: f64) -> Chapter {
+        Chapter {
+            index,
+            title: Some(title.to_string()),
+            start,
+        }
+    }
+
+    #[test]
+    fn the_names_releases_actually_use_are_recognised() {
+        for (name, claim) in [
+            ("OP", Claim::Opening),
+            ("Opening", Claim::Opening),
+            ("OP1 - Again", Claim::Opening),
+            ("02 - Opening", Claim::Opening),
+            ("Opening Song", Claim::Opening),
+            ("NCOP", Claim::Opening),
+            ("オープニング", Claim::Opening),
+            ("ED", Claim::Ending),
+            ("Ending 2", Claim::Ending),
+            ("End Credits", Claim::Ending),
+            ("Cast Roll", Claim::Ending),
+            ("Endcard", Claim::Ending),
+            ("エンディング", Claim::Ending),
+            ("Preview", Claim::Preview),
+            ("Next Episode", Claim::Preview),
+            ("Next Episode Preview", Claim::Preview),
+            ("予告", Claim::Preview),
+        ] {
+            assert_eq!(Claim::of(name), claim, "{name}");
+        }
+    }
+
+    #[test]
+    fn a_chapter_that_merely_starts_with_those_letters_is_not_one() {
+        // The reason this matches words and not prefixes: skipping the viewer
+        // out of "Operation Briefing" would be a bug they cannot undo without
+        // finding the seek bar.
+        for name in ["Operation Briefing", "Editor's cut", "Part A", "Part C", ""] {
+            assert_eq!(Claim::of(name), Claim::Content, "{name}");
+        }
+    }
+
+    /// The names that cannot be settled by reading them.
+    #[test]
+    fn an_ambiguous_name_is_not_decided_by_itself() {
+        assert_eq!(Claim::of("Intro"), Claim::MaybeOpening);
+        assert_eq!(Claim::of("Credits"), Claim::MaybeEnding);
+        assert_eq!(Claim::of("Cast"), Claim::MaybeEnding);
+        // And a chapter read in isolation never resolves to a skip.
+        assert_eq!(chapter(0, "Intro", 0.0).role(), ChapterRole::Content);
+    }
+
+    /// **The first episode of Oshi no Ko.** No opening, no ending — an eighty
+    /// minute episode that begins with a long `Intro` that is the story, and
+    /// ends with a cast scroll. Offering "skip opening" over the first ninety
+    /// seconds of *that* skips the beginning of the series.
+    #[test]
+    fn a_long_intro_is_the_episode_and_not_an_opening() {
+        let chapters = vec![
+            chapter(0, "Intro", 0.0),
+            chapter(1, "Part A", 700.0),
+            chapter(2, "Part B", 2400.0),
+            chapter(3, "Cast", 4680.0),
+        ];
+        let roles = roles(&chapters, Some(4800.0));
+        assert_eq!(
+            roles[0],
+            ChapterRole::Content,
+            "eleven minutes is not a theme"
+        );
+        assert_eq!(
+            roles[3],
+            ChapterRole::Ending,
+            "a cast roll at the end is one"
+        );
+        // Only the cast scroll is the tail; the episode is not skipped into.
+        assert_eq!(credits_start(&chapters, &roles), Some(4680.0));
+    }
+
+    /// The same name in the release that uses it for the theme song: ninety
+    /// seconds, near the front, and no other opening in the file.
+    #[test]
+    fn a_theme_length_intro_near_the_front_is_an_opening() {
+        let chapters = vec![
+            chapter(0, "Avant", 0.0),
+            chapter(1, "Intro", 90.0),
+            chapter(2, "Part A", 180.0),
+        ];
+        assert_eq!(roles(&chapters, Some(1440.0))[1], ChapterRole::Opening);
+
+        // …but not when the file already says which chapter the opening is.
+        let chapters = vec![
+            chapter(0, "Intro", 0.0),
+            chapter(1, "OP", 90.0),
+            chapter(2, "Part A", 180.0),
+        ];
+        let roles = roles(&chapters, Some(1440.0));
+        assert_eq!(roles[0], ChapterRole::Content);
+        assert_eq!(roles[1], ChapterRole::Opening);
+    }
+
+    /// The ordinary shape: the credits and the trailer for next week are one
+    /// run at the end, and the countdown starts where the credits do.
+    #[test]
+    fn the_tail_is_the_whole_run_of_credits_and_preview() {
+        let chapters = vec![
+            chapter(0, "OP", 0.0),
+            chapter(1, "Part A", 90.0),
+            chapter(2, "Part B", 700.0),
+            chapter(3, "ED", 1320.0),
+            chapter(4, "Preview", 1410.0),
+        ];
+        let roles = roles(&chapters, Some(1440.0));
+        assert_eq!(credits_start(&chapters, &roles), Some(1320.0));
+    }
+
+    /// **Episode 46 of Fullmetal Alchemist Brotherhood.** A Part C *after* the
+    /// ending, and the preview after that. Only the preview may be skipped —
+    /// treating everything from the ending on as tail would drop a scene.
+    #[test]
+    fn content_after_the_ending_keeps_the_ending_out_of_the_tail() {
+        let chapters = vec![
+            chapter(0, "Part A", 0.0),
+            chapter(1, "Part B", 700.0),
+            chapter(2, "ED", 1260.0),
+            chapter(3, "Part C", 1350.0),
+            chapter(4, "Preview", 1400.0),
+        ];
+        let roles = roles(&chapters, Some(1440.0));
+        assert_eq!(roles[2], ChapterRole::Ending, "it is still an ending");
+        assert_eq!(credits_start(&chapters, &roles), Some(1400.0));
+    }
+
+    /// A file that ends on the story has no tail at all, and one with no
+    /// chapters has nothing to read.
+    #[test]
+    fn a_file_that_ends_on_content_has_no_tail() {
+        let chapters = vec![chapter(0, "OP", 0.0), chapter(1, "Part A", 90.0)];
+        let roles = roles(&chapters, Some(1440.0));
+        assert_eq!(credits_start(&chapters, &roles), None);
+        assert_eq!(credits_start(&[], &[]), None);
+
+        // Everything skippable is a mis-tagged file, not an episode that is
+        // entirely credits: auto-advancing out of it at second zero would be
+        // worse than doing nothing.
+        let chapters = vec![chapter(0, "OP", 0.0), chapter(1, "ED", 90.0)];
+        let roles = vec![ChapterRole::Ending, ChapterRole::Ending];
+        assert_eq!(credits_start(&chapters, &roles), None);
+    }
+
+    #[test]
+    fn a_position_lands_in_the_chapter_that_contains_it() {
+        let chapters = vec![
+            chapter(0, "Intro", 0.0),
+            chapter(1, "OP", 24.0),
+            chapter(2, "Part A", 114.0),
+        ];
+        assert_eq!(chapter_at(&chapters, 0.0), Some(0));
+        assert_eq!(chapter_at(&chapters, 23.9), Some(0));
+        // Exactly on a boundary belongs to the chapter that starts there,
+        // which is what makes "skip" land *out* of the opening rather than at
+        // its last frame.
+        assert_eq!(chapter_at(&chapters, 24.0), Some(1));
+        assert_eq!(chapter_at(&chapters, 3000.0), Some(2));
+    }
+
+    #[test]
+    fn a_chapter_before_the_first_one_starts_is_in_no_chapter() {
+        let chapters = vec![chapter(0, "OP", 24.0)];
+        assert_eq!(chapter_at(&chapters, 0.0), None);
+    }
+
+    #[test]
+    fn the_last_chapter_ends_where_the_file_does() {
+        let chapters = vec![chapter(0, "OP", 0.0), chapter(1, "Part A", 90.0)];
+        assert_eq!(chapter_end(&chapters, 0, Some(1440.0)), Some(90.0));
+        assert_eq!(chapter_end(&chapters, 1, Some(1440.0)), Some(1440.0));
+        // No duration yet and nothing after it: there is nowhere to skip to,
+        // and a button that seeks to zero would be worse than no button.
+        assert_eq!(chapter_end(&chapters, 1, None), None);
+    }
+}

crates/pstr-core/src/lib.rs

@@ -7,6 +7,7 @@
 
 pub mod appearance;
 pub mod catalog;
+pub mod chapters;
 pub mod config;
 pub mod error;
 pub mod library;

crates/pstr-core/src/prefs.rs

@@ -18,6 +18,11 @@ use crate::error::Result;
 /// referenced here because `pstr-core` does not depend on the player.
 const MAX_VOLUME: f64 = 100.0;
 
+/// The range of playback rates offered. Past these, audio stops being speech
+/// and video stops being watchable, and mpv's own resampler gives up first.
+const MIN_SPEED: f64 = 0.25;
+const MAX_SPEED: f64 = 4.0;
+
 /// How playback should sound, and in which language.
 #[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
 // A file written by an older version, or hand-edited, is missing fields rather
@@ -43,6 +48,18 @@ pub struct PlaybackPrefs {
     /// does and what a season of anything is watched like. Off is one checkbox
     /// away for someone who falls asleep to it.
     pub autoplay_next: bool,
+    /// Whether an opening or ending is seeked past rather than offered.
+    ///
+    /// Off by default, and deliberately: chapter names are a guess about a file
+    /// somebody else muxed, and a wrong guess that only greys out a button
+    /// costs nothing while a wrong guess that seeks costs the scene.
+    pub auto_skip: bool,
+    /// How fast playback runs, 1.0 being the file's own rate.
+    ///
+    /// Kept across episodes deliberately: someone who watches at 1.25 watches
+    /// everything at 1.25, and a speed that reset every episode would be a
+    /// setting nobody could use.
+    pub speed: f64,
 }
 
 impl Default for PlaybackPrefs {
@@ -54,6 +71,8 @@ impl Default for PlaybackPrefs {
             subtitle_language: None,
             subtitles: true,
             autoplay_next: true,
+            auto_skip: false,
+            speed: 1.0,
         }
     }
 }
@@ -68,6 +87,10 @@ impl PlaybackPrefs {
             self.volume = MAX_VOLUME;
         }
         self.volume = self.volume.clamp(0.0, MAX_VOLUME);
+        if !self.speed.is_finite() {
+            self.speed = 1.0;
+        }
+        self.speed = self.speed.clamp(MIN_SPEED, MAX_SPEED);
         self.audio_language = self.audio_language.filter(|tag| !tag.trim().is_empty());
         self.subtitle_language = self.subtitle_language.filter(|tag| !tag.trim().is_empty());
         self
@@ -124,6 +147,8 @@ mod tests {
             subtitle_language: Some("eng".into()),
             subtitles: true,
             autoplay_next: false,
+            auto_skip: true,
+            speed: 1.5,
         };
         save(&dirs, &prefs).unwrap();
         assert_eq!(load(&dirs).unwrap(), prefs);

crates/pstr-core/src/shares.rs

@@ -160,6 +160,49 @@ impl ShareStore {
         Ok(share)
     }
 
+    /// Re-supply a configured share's secrets, keeping everything else.
+    ///
+    /// A secret store can lose the ability to read what it wrote: an Android
+    /// Keystore key is invalidated by a lockscreen change or a device restore,
+    /// and a desktop keyring can be reset. After that every open of the share
+    /// fails — and so, often, does removing it, because removal deletes a
+    /// secret the store can no longer touch. Re-entering the link is the way
+    /// back that does not cost the catalog and the offline files.
+    ///
+    /// The link must be the same one: a different token is a different share,
+    /// and quietly repointing an existing library at it would leave every
+    /// catalog row describing files that are no longer there.
+    pub fn replace_secrets(
+        &self,
+        id: &str,
+        url: &str,
+        custom_password: Option<&str>,
+    ) -> Result<Share> {
+        let token = token_from_url(url)?;
+        let mut shares = self.list()?;
+        let share = shares
+            .iter_mut()
+            .find(|share| share.id == id)
+            .ok_or_else(|| Error::NotFound(format!("no share with id {id}")))?;
+        if share.token != token {
+            return Err(Error::Config(
+                "that link is for a different share; add it as a new one".to_owned(),
+            ));
+        }
+
+        let secrets = ShareSecrets {
+            url: url.to_string(),
+            custom_password: custom_password
+                .filter(|password| !password.is_empty())
+                .map(str::to_string),
+        };
+        self.store_secrets(id, &secrets)?;
+        share.has_custom_password = secrets.custom_password.is_some();
+        let updated = share.clone();
+        write_json(&self.dirs.shares_file(), &shares)?;
+        Ok(updated)
+    }
+
     /// Forget a share and its secrets.
     ///
     /// The config entry goes first here, for the mirror-image reason: if the
@@ -223,10 +266,28 @@ impl SharedLibrary {
     /// the whole library — one revoked link should not make the other three
     /// unwatchable.
     pub async fn open_all(store: &ShareStore) -> Result<(Self, Vec<(Share, Error)>)> {
+        Self::open_all_reusing(store, BTreeMap::new()).await
+    }
+
+    /// Open every configured share, reusing the clients in `reusable`.
+    ///
+    /// Adding or removing one link should not cost a fresh handshake for the
+    /// shares that were already open, so a caller that still holds them can
+    /// hand them back here. A share whose stored secrets changed must *not*
+    /// appear in `reusable` — its old client authenticates against the old
+    /// link.
+    pub async fn open_all_reusing(
+        store: &ShareStore,
+        mut reusable: BTreeMap<String, ProtonDrivePublicLinkClient>,
+    ) -> Result<(Self, Vec<(Share, Error)>)> {
         let mut clients = BTreeMap::new();
         let mut failures = Vec::new();
 
         for share in store.list()? {
+            if let Some(client) = reusable.remove(&share.id) {
+                clients.insert(share.id, client);
+                continue;
+            }
             match store.open(&share).await {
                 Ok(client) => {
                     clients.insert(share.id.clone(), client);
@@ -238,6 +299,23 @@ impl SharedLibrary {
         Ok((Self { clients }, failures))
     }
 
+    /// The opened clients, minus `dropping`, ready to hand to
+    /// [`SharedLibrary::open_all_reusing`].
+    ///
+    /// The excluded share is the one whose credentials or membership just
+    /// changed; leaving it out is what makes a removed share's live client
+    /// unreachable rather than merely stale.
+    pub fn reusable_clients(
+        &self,
+        dropping: &str,
+    ) -> BTreeMap<String, ProtonDrivePublicLinkClient> {
+        self.clients
+            .iter()
+            .filter(|(id, _)| id.as_str() != dropping)
+            .map(|(id, client)| (id.clone(), client.clone()))
+            .collect()
+    }
+
     /// The client for one share.
     pub fn client(&self, share_id: &str) -> Option<&ProtonDrivePublicLinkClient> {
         self.clients.get(share_id)
@@ -259,43 +337,77 @@ impl SharedLibrary {
         Ok(())
     }
 
-    /// Walk one share's whole subtree, depth first, yielding every node.
+    /// Walk one share's whole subtree, level by level, yielding every node.
     ///
     /// There is no recursion helper on the visitor path — the authenticated
     /// client's `get_node_hierarchy` / `get_node_by_path` have no counterpart
     /// there — so the walk is here.
+    ///
+    /// **Breadth first and fanned out, because a media share is wide.** The
+    /// shape of one is a root holding a folder per series, each holding a folder
+    /// per season: a couple of hundred folders that are each one listing request
+    /// plus a detail fetch, and almost all of them siblings. Walking that one
+    /// folder at a time spends the whole crawl waiting on a round trip it could
+    /// have overlapped — the crawl was minutes of latency and seconds of work.
+    /// Taking a whole level at once is what collapses it.
+    ///
+    /// The client is cheap to clone and its clones share one node-key cache and
+    /// one single-flight map, so siblings that need the same ancestor key wait
+    /// on one derivation rather than each starting their own. `buffered` rather
+    /// than `buffer_unordered`: the crawl's output order is otherwise a race,
+    /// and a catalog that reorders itself between two identical crawls is
+    /// needlessly hard to diff.
     pub async fn crawl(&self, share_id: &str) -> Result<Vec<Node>> {
+        use futures::stream::{StreamExt as _, TryStreamExt as _};
+
         let client = self
             .client(share_id)
             .ok_or_else(|| Error::NotFound(format!("share {share_id} is not open")))?;
 
         let root = client.get_root_node().await?;
-        let mut found = Vec::new();
-        let mut folders = vec![root.uid.clone()];
-        found.push(root);
+        let mut level = vec![root.uid.clone()];
+        let mut found = vec![root];
 
-        while let Some(folder) = folders.pop() {
-            let child_uids: Vec<NodeUid> =
-                client.enumerate_folder_children_node_uids(&folder).await?;
-            if child_uids.is_empty() {
-                continue;
-            }
-            // Chunked and fanned out inside the SDK, and the node keys it
-            // unlocks along the way are cached there, so a deep tree does not
-            // re-derive the same ancestors per child.
-            let children = client.enumerate_nodes(&child_uids).await?;
-            for child in children {
-                if child.is_folder() {
-                    folders.push(child.uid.clone());
+        while !level.is_empty() {
+            let listings = level.into_iter().map(|folder| {
+                let client = client.clone();
+                async move {
+                    let child_uids: Vec<NodeUid> =
+                        client.enumerate_folder_children_node_uids(&folder).await?;
+                    if child_uids.is_empty() {
+                        return Ok(Vec::new());
+                    }
+                    // Chunked and fanned out inside the SDK too, so this is a
+                    // multiplier on that concurrency rather than the only one.
+                    client.enumerate_nodes(&child_uids).await
+                }
+            });
+
+            let mut listings = futures::stream::iter(listings).buffered(CRAWL_CONCURRENCY);
+            let mut next = Vec::new();
+            while let Some(children) = listings.try_next().await? {
+                for child in children {
+                    if child.is_folder() {
+                        next.push(child.uid.clone());
+                    }
+                    found.push(child);
                 }
-                found.push(child);
             }
+            level = next;
         }
 
         Ok(found)
     }
 }
 
+/// How many folders of one level to list at once.
+///
+/// Each of these fans out again inside the SDK — up to four detail batches per
+/// folder — so this is not the number of requests in flight but a multiplier on
+/// it. Six keeps the ceiling in the low tens: enough to hide the round trip on
+/// a wide level, well short of a burst a share server would read as abuse.
+const CRAWL_CONCURRENCY: usize = 6;
+
 /// The app-version string Proton identifies this client by.
 ///
 /// The `external-drive-` prefix is **not** decoration: the API parses the part
@@ -396,6 +508,105 @@ mod tests {
         }
     }
 
+    /// A store that has forgotten how to read what it wrote, which is what an
+    /// invalidated Android Keystore key looks like from Rust.
+    #[derive(Default)]
+    struct Unreadable {
+        entries: std::sync::Mutex<BTreeMap<String, String>>,
+        readable: std::sync::atomic::AtomicBool,
+    }
+
+    impl SecretStore for Unreadable {
+        fn set(&self, key: &str, value: &str) -> Result<()> {
+            self.entries
+                .lock()
+                .unwrap()
+                .insert(key.to_owned(), value.to_owned());
+            self.readable
+                .store(true, std::sync::atomic::Ordering::Relaxed);
+            Ok(())
+        }
+
+        fn get(&self, key: &str) -> Result<Option<String>> {
+            if !self.readable.load(std::sync::atomic::Ordering::Relaxed) {
+                return Err(Error::Config("key permanently invalidated".into()));
+            }
+            Ok(self.entries.lock().unwrap().get(key).cloned())
+        }
+
+        fn delete(&self, key: &str) -> Result<()> {
+            self.entries.lock().unwrap().remove(key);
+            Ok(())
+        }
+    }
+
+    fn store_in(name: &str) -> (ShareStore, Arc<Unreadable>) {
+        let root = std::env::temp_dir().join(format!("pstr-shares-{name}-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&root);
+        let dirs = AppDirs::from_paths(root.join("config"), root.join("data"), root.join("cache"))
+            .expect("app directories");
+        let secrets = Arc::new(Unreadable::default());
+        (
+            ShareStore::with_secret_store(dirs, secrets.clone()),
+            secrets,
+        )
+    }
+
+    /// The way back from an unreadable secret store. The share keeps its id, so
+    /// the catalog rows and offline files keyed by it stay valid — which is the
+    /// whole reason this exists rather than Remove-and-re-add.
+    #[test]
+    fn a_re_entered_link_restores_a_share_whose_secret_cannot_be_read() {
+        let (store, secrets) = store_in("repair");
+        let url = "https://drive.proton.me/urls/ABC123#s3cr3t";
+        let added = store.add("Library", url, None).expect("add");
+
+        secrets
+            .readable
+            .store(false, std::sync::atomic::Ordering::Relaxed);
+        assert!(store.load_secrets(&added.id).is_err());
+
+        let repaired = store
+            .replace_secrets(&added.id, url, Some("new-password"))
+            .expect("replace");
+        assert_eq!(repaired.id, added.id);
+        assert!(repaired.has_custom_password);
+        assert!(
+            store
+                .list()
+                .expect("list")
+                .iter()
+                .any(|share| share.id == added.id && share.has_custom_password)
+        );
+    }
+
+    /// A different link is a different share. Repointing this one at it would
+    /// leave every catalog row and offline file describing files that are not
+    /// there.
+    #[test]
+    fn a_re_entered_link_for_a_different_share_is_refused() {
+        let (store, _) = store_in("repair-mismatch");
+        let added = store
+            .add(
+                "Library",
+                "https://drive.proton.me/urls/ABC123#s3cr3t",
+                None,
+            )
+            .expect("add");
+
+        let error = store
+            .replace_secrets(
+                &added.id,
+                "https://drive.proton.me/urls/DEF456#s3cr3t",
+                None,
+            )
+            .expect_err("a different token must be refused");
+        assert!(
+            error.to_string().contains("different share"),
+            "says what is wrong: {error}"
+        );
+    }
+
     /// The id must be derivable from the token alone — deriving it from the URL
     /// would mix a secret into the config file.
     #[test]

crates/pstr-meta/Cargo.toml

@@ -10,6 +10,8 @@ authors.workspace = true
 
 [dependencies]
 pstr-core.workspace = true
+# `time` for the rate limiter's sleeps, `sync` for the mutex it paces behind.
+tokio = { workspace = true, features = ["time", "sync"] }
 serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
@@ -19,4 +21,4 @@ tracing.workspace = true
 reqwest.workspace = true
 
 [dev-dependencies]
-tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+tokio = { workspace = true, features = ["macros", "rt-multi-thread", "test-util"] }

crates/pstr-meta/src/anilist.rs

@@ -14,11 +14,30 @@ use pstr_core::metadata::{EpisodeMetadata, ProviderId, TitleMetadata};
 use serde::Deserialize;
 
 use crate::error::{Error, Result};
+use crate::limiter::RateLimiter;
 use crate::matching::{Candidate, Query};
 use crate::provider::Provider;
 
 const ENDPOINT: &str = "https://graphql.anilist.co";
 
+/// What AniList documents as its ceiling: ninety requests a minute.
+///
+/// A starting point, not a belief — the API has been running in a degraded mode
+/// that allows thirty for a long time now, and says so in `X-RateLimit-Limit` on
+/// every answer. The limiter retunes itself off that header after the first
+/// request, so the only cost of starting optimistic is one `429` on a run that
+/// begins during a degraded window.
+const REQUESTS_PER_MINUTE: u32 = 90;
+
+/// How many times to sit out a `429` before giving up on one request.
+///
+/// Two, because the pause it asks for is the rest of its rate-limit window and
+/// the limiter holds every other lookup for the same stretch — a third round is
+/// minutes of a scan spent waiting rather than matching. Giving up returns
+/// [`Error::RateLimited`], which is a failure and therefore not cached: the
+/// title stays askable and the next run picks it up.
+const RETRIES: usize = 2;
+
 /// How many answers to score. AniList's own relevance ordering is good, and the
 /// right title is essentially always in the first handful; asking for more costs
 /// them bandwidth and buys nothing.
@@ -66,11 +85,16 @@ query ($id: Int) {
 
 pub struct AniList {
     http: reqwest::Client,
+    /// Shared by every lookup in flight — see [`crate::limiter`].
+    limiter: RateLimiter,
 }
 
 impl AniList {
     pub fn new(http: reqwest::Client) -> Self {
-        Self { http }
+        Self {
+            http,
+            limiter: RateLimiter::per_minute(REQUESTS_PER_MINUTE),
+        }
     }
 }
 
@@ -132,24 +156,40 @@ impl Provider for AniList {
 }
 
 impl AniList {
-    /// One GraphQL request, with AniList's two ways of failing — an HTTP status
-    /// and an `errors` array under a 200 — folded into one.
+    /// One GraphQL request, paced, with AniList's two ways of failing — an HTTP
+    /// status and an `errors` array under a 200 — folded into one.
+    ///
+    /// A `429` is waited out rather than returned: a scan sends hundreds of
+    /// these, and the request that trips the limit is not the one that was
+    /// wrong. See [`crate::limiter`].
     async fn query<T: serde::de::DeserializeOwned>(
         &self,
         body: serde_json::Value,
     ) -> Result<Option<T>> {
-        let response = self.http.post(ENDPOINT).json(&body).send().await?;
-        let status = response.status();
-        if !status.is_success() {
-            // 429 is the one worth naming: AniList rate-limits by the minute,
-            // and a caller that knows it was throttled can back off rather than
-            // cache a miss for a title that would have matched.
-            return Err(if status.as_u16() == 429 {
-                Error::RateLimited
-            } else {
-                Error::Http(format!("AniList answered {status}"))
-            });
-        }
+        let mut attempts = 0usize;
+        let response = loop {
+            self.limiter.acquire().await;
+            let response = self.http.post(ENDPOINT).json(&body).send().await?;
+            let status = response.status();
+
+            if status.as_u16() == 429 {
+                // The pause holds every other lookup too, so the rest of the
+                // run does not spend the window earning more 429s.
+                let waited = self.limiter.throttled(response.headers()).await;
+                attempts += 1;
+                if attempts > RETRIES {
+                    return Err(Error::RateLimited);
+                }
+                tracing::debug!("AniList is throttling; waiting {waited:?}");
+                continue;
+            }
+
+            self.limiter.observe(response.headers()).await;
+            if !status.is_success() {
+                return Err(Error::Http(format!("AniList answered {status}")));
+            }
+            break response;
+        };
 
         let payload: Response<T> = response.json().await?;
         if let Some(errors) = payload.errors

crates/pstr-meta/src/lib.rs

@@ -29,6 +29,7 @@
 
 pub mod anilist;
 pub mod error;
+pub mod limiter;
 pub mod matching;
 pub mod provider;
 pub mod service;

crates/pstr-meta/src/limiter.rs

@@ -0,0 +1,227 @@
+//! Spacing requests out, so a provider does not have to.
+//!
+//! Scanning a new library is the one moment this app talks to a metadata
+//! provider in bulk: every title is one search, a matched series is one more
+//! request per season, and a hundred-folder share is several hundred requests
+//! in a burst. AniList allows ninety a minute — thirty while its API is in the
+//! degraded mode it has been in for a while — and answers everything past that
+//! with a `429`. Without pacing, the first thirty titles match and the rest of
+//! the run fails; because a failure is deliberately not cached (see
+//! [`crate::service`]), the next scan starts over and fails in the same place.
+//!
+//! So requests take a slot here first. The rate is not a constant but the
+//! provider's own: `X-RateLimit-Limit` on any answer retunes it, and a `429`
+//! parks every caller for as long as `Retry-After` asks. One limiter is shared
+//! by every lookup in flight — it lives in the provider, the provider lives in
+//! an `Arc` inside [`crate::MetadataService`], and cloning the service to hand
+//! it to a worker shares the limiter rather than copying it.
+
+use std::time::Duration;
+
+use tokio::sync::Mutex;
+use tokio::time::Instant;
+
+/// Never faster than this, whatever a header claims.
+const MIN_INTERVAL: Duration = Duration::from_millis(20);
+
+/// Never slower than this. A provider that asks for a longer pause gets it via
+/// [`RateLimiter::throttled`]; this is only the floor the steady rate decays to,
+/// so a misread header cannot wedge a scan forever.
+const MAX_INTERVAL: Duration = Duration::from_secs(5);
+
+/// How long to honour a `429` that came with no `Retry-After`.
+const DEFAULT_BACKOFF: Duration = Duration::from_secs(60);
+
+/// The longest a single throttle may park requests for.
+///
+/// A scan is something a person is watching happen. Two minutes of silence is
+/// worse than a partial answer they can ask to complete later, and the titles
+/// that did not get through stay unmatched and askable.
+const MAX_BACKOFF: Duration = Duration::from_secs(30);
+
+/// A shared, self-tuning pacer for one provider's API.
+pub struct RateLimiter {
+    state: Mutex<State>,
+}
+
+struct State {
+    /// The earliest a request may be sent.
+    next: Instant,
+    /// The spacing between requests.
+    interval: Duration,
+}
+
+impl RateLimiter {
+    /// A limiter starting at `per_minute` requests a minute.
+    ///
+    /// A starting point only: the first answer that carries a limit header
+    /// replaces it with what the provider actually allows right now.
+    pub fn per_minute(per_minute: u32) -> Self {
+        Self::new(interval_for(per_minute.max(1)))
+    }
+
+    fn new(interval: Duration) -> Self {
+        Self {
+            state: Mutex::new(State {
+                next: Instant::now(),
+                interval,
+            }),
+        }
+    }
+
+    /// Wait until a request may be sent, then claim that slot.
+    ///
+    /// Re-checks after every sleep rather than reserving a slot up front, so a
+    /// [`throttled`](Self::throttled) that lands while callers are already
+    /// waiting holds them too — which is the whole point of a shared limiter
+    /// during a burst.
+    pub async fn acquire(&self) {
+        loop {
+            let wait = {
+                let mut state = self.state.lock().await;
+                let now = Instant::now();
+                if state.next <= now {
+                    state.next = now + state.interval;
+                    return;
+                }
+                state.next - now
+            };
+            tokio::time::sleep(wait).await;
+        }
+    }
+
+    /// Retune from a provider's own rate-limit headers.
+    pub async fn observe(&self, headers: &reqwest::header::HeaderMap) {
+        let Some(limit) = header_number(headers, "x-ratelimit-limit") else {
+            return;
+        };
+        let interval = interval_for(limit.max(1) as u32);
+        let mut state = self.state.lock().await;
+        if state.interval != interval {
+            tracing::debug!("provider allows {limit}/min; pacing at {interval:?}");
+            state.interval = interval;
+        }
+    }
+
+    /// Park every caller after a `429`.
+    ///
+    /// `Retry-After` is seconds, and is the provider telling us exactly how
+    /// long its window has left to run — a shorter guess would just earn
+    /// another `429`.
+    pub async fn throttled(&self, headers: &reqwest::header::HeaderMap) -> Duration {
+        let wait = header_number(headers, "retry-after")
+            .map(|seconds| Duration::from_secs(seconds.max(1)))
+            .unwrap_or(DEFAULT_BACKOFF)
+            .min(MAX_BACKOFF);
+
+        let mut state = self.state.lock().await;
+        let until = Instant::now() + wait;
+        if until > state.next {
+            state.next = until;
+        }
+        wait
+    }
+}
+
+/// `90` a minute → one every 667ms.
+fn interval_for(per_minute: u32) -> Duration {
+    Duration::from_secs_f64(60.0 / f64::from(per_minute)).clamp(MIN_INTERVAL, MAX_INTERVAL)
+}
+
+fn header_number(headers: &reqwest::header::HeaderMap, name: &str) -> Option<u64> {
+    headers.get(name)?.to_str().ok()?.trim().parse::<u64>().ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn headers(pairs: &[(&str, &str)]) -> reqwest::header::HeaderMap {
+        let mut map = reqwest::header::HeaderMap::new();
+        for (name, value) in pairs {
+            map.insert(
+                reqwest::header::HeaderName::from_bytes(name.as_bytes()).expect("header name"),
+                value.parse().expect("header value"),
+            );
+        }
+        map
+    }
+
+    #[test]
+    fn a_rate_becomes_the_spacing_it_implies() {
+        assert_eq!(interval_for(60), Duration::from_secs(1));
+        assert_eq!(interval_for(30), Duration::from_secs(2));
+        // Clamped at both ends: a provider claiming one request a minute must
+        // not stall a scan for a minute per title, and one claiming a million
+        // still gets paced.
+        assert_eq!(interval_for(1), MAX_INTERVAL);
+        assert_eq!(interval_for(1_000_000), MIN_INTERVAL);
+    }
+
+    #[tokio::test]
+    async fn the_first_request_of_a_run_does_not_wait() {
+        let limiter = RateLimiter::per_minute(30);
+        let started = Instant::now();
+        limiter.acquire().await;
+        assert!(started.elapsed() < Duration::from_millis(50));
+    }
+
+    /// The one that matters: two requests in a row are spaced, not sent
+    /// together.
+    #[tokio::test(start_paused = true)]
+    async fn a_second_request_waits_out_the_interval() {
+        let limiter = RateLimiter::per_minute(60);
+        limiter.acquire().await;
+        let started = Instant::now();
+        limiter.acquire().await;
+        assert!(started.elapsed() >= Duration::from_secs(1));
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn a_429_parks_the_next_request_for_as_long_as_it_asked() {
+        let limiter = RateLimiter::per_minute(600);
+        let waited = limiter.throttled(&headers(&[("retry-after", "12")])).await;
+        assert_eq!(waited, Duration::from_secs(12));
+
+        let started = Instant::now();
+        limiter.acquire().await;
+        assert!(started.elapsed() >= Duration::from_secs(12));
+    }
+
+    /// A throttle with no header still has to park for something, and a
+    /// ridiculous one is capped — a scan is something a person is watching.
+    #[tokio::test]
+    async fn a_429_without_a_header_backs_off_by_a_capped_default() {
+        let limiter = RateLimiter::per_minute(90);
+        assert_eq!(
+            limiter.throttled(&headers(&[])).await,
+            DEFAULT_BACKOFF.min(MAX_BACKOFF)
+        );
+        assert_eq!(
+            limiter
+                .throttled(&headers(&[("retry-after", "86400")]))
+                .await,
+            MAX_BACKOFF
+        );
+    }
+
+    #[tokio::test]
+    async fn the_provider_s_own_limit_retunes_the_pacing() {
+        let limiter = RateLimiter::per_minute(90);
+        limiter
+            .observe(&headers(&[("x-ratelimit-limit", "30")]))
+            .await;
+        assert_eq!(
+            limiter.state.lock().await.interval,
+            Duration::from_secs(2),
+            "AniList's degraded mode allows 30/min and says so on every answer"
+        );
+
+        // Nonsense, and an absent header, leave the pacing alone.
+        limiter
+            .observe(&headers(&[("x-ratelimit-limit", "soon")]))
+            .await;
+        limiter.observe(&headers(&[])).await;
+        assert_eq!(limiter.state.lock().await.interval, Duration::from_secs(2));
+    }
+}

crates/pstr-meta/src/service.rs

@@ -223,6 +223,54 @@ impl MetadataService {
         Ok(episodes)
     }
 
+    /// The episode list for a whole title, with a failure treated as an empty
+    /// one.
+    ///
+    /// Deliberately not fatal to the title it belongs to: a poster and a
+    /// synopsis that arrived are worth keeping even when the episode request
+    /// was the one that hit the rate limit. The empty result is not cached as
+    /// an answer — the next match run asks again — because the only thing that
+    /// triggers one is a viewer pressing the button.
+    ///
+    /// The match itself only ever answers for *one* entry, and on a provider
+    /// that files each sequel separately — AniList — that entry is season one.
+    /// So each further season of the title is searched for by name and its
+    /// episodes are tagged with the season they came from; without that,
+    /// seasons two and three have no episode names at all. See
+    /// [`MetadataService::season_episodes`].
+    pub async fn title_episodes(
+        &self,
+        title: &Title,
+        found: &TitleMetadata,
+    ) -> Vec<EpisodeMetadata> {
+        let mut episodes = self
+            .episodes(found)
+            .await
+            .inspect_err(|error| tracing::warn!("episodes for {}: {error}", found.name))
+            .unwrap_or_default();
+
+        if !self.splits_seasons() {
+            return episodes;
+        }
+
+        // Season one is what the title's own match already answered for.
+        let later: Vec<u32> = title
+            .seasons
+            .iter()
+            .filter_map(|season| season.number)
+            .filter(|number| *number > 1)
+            .collect();
+        for season in later {
+            match self.season_episodes(title, season).await {
+                Ok(found) => episodes.extend(found),
+                Err(error) => {
+                    tracing::warn!("episodes for {} season {season}: {error}", title.name);
+                }
+            }
+        }
+        episodes
+    }
+
     /// Whether this provider files a sequel as its own entry, so that a title
     /// with several seasons has to be searched for once per season.
     pub fn splits_seasons(&self) -> bool {

crates/pstr-meta/src/tmdb.rs

@@ -15,6 +15,7 @@ use pstr_core::metadata::{EpisodeMetadata, ProviderId, TitleMetadata};
 use serde::Deserialize;
 
 use crate::error::{Error, Result};
+use crate::limiter::RateLimiter;
 use crate::matching::{Candidate, Query};
 use crate::provider::Provider;
 
@@ -37,13 +38,23 @@ const STILL_SIZE: &str = "w300";
 /// at here, give or take; `original` is several megabytes of print-resolution
 /// artwork per title, which is bandwidth spent on pixels no tile can show.
 const IMAGE_BASE: &str = "https://image.tmdb.org/t/p";
+
 const POSTER_SIZE: &str = "w500";
 const BACKDROP_SIZE: &str = "w780";
 
+/// TMDB's published ceiling is around fifty requests a second and it no longer
+/// enforces a daily one. This is well under it: the point of pacing here is a
+/// burst that would look like abuse, not a rate anyone is close to.
+const REQUESTS_PER_MINUTE: u32 = 600;
+
+/// As [`crate::anilist`]'s.
+const RETRIES: usize = 2;
+
 pub struct Tmdb {
     http: reqwest::Client,
     api_key: String,
     language: String,
+    limiter: RateLimiter,
 }
 
 impl Tmdb {
@@ -52,6 +63,7 @@ impl Tmdb {
             http,
             api_key,
             language,
+            limiter: RateLimiter::per_minute(REQUESTS_PER_MINUTE),
         }
     }
 }
@@ -72,28 +84,12 @@ impl Provider for Tmdb {
             return Err(Error::MissingApiKey(ProviderId::Tmdb));
         }
 
-        let response = self
-            .http
-            .get(ENDPOINT)
-            .query(&[
-                ("api_key", self.api_key.as_str()),
-                ("query", query.name.as_str()),
-                ("language", self.language.as_str()),
-                ("include_adult", "false"),
-            ])
-            .send()
+        let payload: SearchResponse = self
+            .get(
+                ENDPOINT,
+                &[("query", query.name.as_str()), ("include_adult", "false")],
+            )
             .await?;
-
-        let status = response.status();
-        if !status.is_success() {
-            return Err(match status.as_u16() {
-                401 => Error::MissingApiKey(ProviderId::Tmdb),
-                429 => Error::RateLimited,
-                _ => Error::Http(format!("TMDB answered {status}")),
-            });
-        }
-
-        let payload: SearchResponse = response.json().await?;
         Ok(payload
             .results
             .into_iter()
@@ -172,7 +168,11 @@ impl Provider for Tmdb {
 }
 
 impl Tmdb {
-    /// One authenticated GET, with TMDB's failures named.
+    /// One authenticated GET, paced, with TMDB's failures named.
+    ///
+    /// TMDB is far more generous than AniList and a library-sized run rarely
+    /// troubles it, but the pacing costs nothing here and the `429` handling is
+    /// the same code — see [`crate::limiter`].
     async fn get<T: serde::de::DeserializeOwned>(
         &self,
         url: &str,
@@ -181,23 +181,40 @@ impl Tmdb {
         if self.api_key.trim().is_empty() {
             return Err(Error::MissingApiKey(ProviderId::Tmdb));
         }
-        let mut request = self.http.get(url).query(&[
-            ("api_key", self.api_key.as_str()),
-            ("language", self.language.as_str()),
-        ]);
-        for pair in extra {
-            request = request.query(&[pair]);
-        }
 
-        let response = request.send().await?;
-        let status = response.status();
-        if !status.is_success() {
-            return Err(match status.as_u16() {
-                401 => Error::MissingApiKey(ProviderId::Tmdb),
-                429 => Error::RateLimited,
-                _ => Error::Http(format!("TMDB answered {status}")),
-            });
-        }
+        let mut attempts = 0usize;
+        let response = loop {
+            let mut request = self.http.get(url).query(&[
+                ("api_key", self.api_key.as_str()),
+                ("language", self.language.as_str()),
+            ]);
+            for pair in extra {
+                request = request.query(&[pair]);
+            }
+
+            self.limiter.acquire().await;
+            let response = request.send().await?;
+            let status = response.status();
+
+            if status.as_u16() == 429 {
+                let waited = self.limiter.throttled(response.headers()).await;
+                attempts += 1;
+                if attempts > RETRIES {
+                    return Err(Error::RateLimited);
+                }
+                tracing::debug!("TMDB is throttling; waiting {waited:?}");
+                continue;
+            }
+
+            if !status.is_success() {
+                return Err(match status.as_u16() {
+                    401 => Error::MissingApiKey(ProviderId::Tmdb),
+                    _ => Error::Http(format!("TMDB answered {status}")),
+                });
+            }
+            break response;
+        };
+
         Ok(response.json().await?)
     }
 }

crates/pstr-player/Cargo.toml

@@ -9,6 +9,9 @@ rust-version.workspace = true
 authors.workspace = true
 
 [dependencies]
+# For `chapters`, which Android reaches through its own bridge and so cannot
+# live here. Already in the tree via pstr-stream.
+pstr-core.workspace = true
 pstr-stream.workspace = true
 tokio.workspace = true
 thiserror.workspace = true

crates/pstr-player/src/chapters.rs

@@ -1,280 +1,19 @@
-//! The chapters a file was muxed with, and what they are for.
+//! Reading the chapter list out of the player.
+//!
+//! The chapters themselves — what a name claims, what the rest of the file
+//! settles, where the tail begins — live in [`pstr_core::chapters`], because
+//! Android reads its chapter list through its own JNI adapter and must reach
+//! the same verdict as this crate does. Only the mpv read is here.
 //!
 //! Read the same way as the track list — `chapter-list/N/title`, one
 //! sub-property at a time — for the same reason: those are plain strings and
 //! doubles, and a node walk would buy nothing.
-//!
-//! Anime releases mark their opening and ending as chapters, which is the whole
-//! reason this exists: with them a player can offer to skip the ninety seconds
-//! everyone skips, and without them it cannot.
 
 use libmpv2::Mpv;
 
-/// One chapter of the file.
-#[derive(Debug, Clone, PartialEq)]
-pub struct Chapter {
-    /// Position in the list, which is what mpv's `chapter` property is set to.
-    pub index: i64,
-    /// The name the muxer gave it, if any.
-    pub title: Option<String>,
-    /// Where it starts, in seconds.
-    pub start: f64,
-}
-
-impl Chapter {
-    /// What to show in a list. A nameless chapter is still worth an entry —
-    /// it is a place in the file — so it gets its number.
-    pub fn label(&self) -> String {
-        match &self.title {
-            Some(title) => title.clone(),
-            None => format!("Chapter {}", self.index + 1),
-        }
-    }
-
-    /// What this chapter is, from its name alone.
-    ///
-    /// Prefer [`roles`], which resolves the names that only mean one thing *in
-    /// context* — a chapter called `Intro` is an opening in one release and the
-    /// first ten minutes of the story in another.
-    pub fn role(&self) -> ChapterRole {
-        match Claim::of(self.title.as_deref().unwrap_or_default()) {
-            Claim::Opening => ChapterRole::Opening,
-            Claim::Ending => ChapterRole::Ending,
-            Claim::Preview => ChapterRole::Preview,
-            // Unresolved without the rest of the file: assume it is content,
-            // which is the reading that never skips anything.
-            _ => ChapterRole::Content,
-        }
-    }
-}
-
-/// The kinds of chapter worth treating differently from "part of the episode".
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum ChapterRole {
-    /// The opening titles.
-    Opening,
-    /// The ending titles.
-    Ending,
-    /// A preview of the next episode, after the ending.
-    Preview,
-    /// Anything else, including everything unnamed.
-    Content,
-}
-
-impl ChapterRole {
-    /// What a button offering to skip this should say. `None` for a chapter
-    /// nobody wants skipped.
-    pub fn skip_label(self) -> Option<&'static str> {
-        match self {
-            Self::Opening => Some("Skip opening"),
-            Self::Ending => Some("Skip ending"),
-            Self::Preview => Some("Skip preview"),
-            Self::Content => None,
-        }
-    }
-
-    /// Whether this is something the file could end on without the viewer
-    /// missing anything: credits and a trailer for next week.
-    ///
-    /// An *opening* is not, even though it is skippable — a file does not end
-    /// with one, and treating it as tail would make a mis-tagged chapter
-    /// auto-advance out of the episode.
-    pub fn ends_the_episode(self) -> bool {
-        matches!(self, Self::Ending | Self::Preview)
-    }
-}
-
-/// What a chapter's *name* claims, before the rest of the file is consulted.
-///
-/// The two `Maybe` variants are the whole reason this is separate from
-/// [`ChapterRole`]. `Intro` is the opening in one release and, in the first
-/// episode of Oshi no Ko, a ten-minute introduction to the series that a viewer
-/// must not be skipped out of. `Credits` and `Cast` are the ending in most
-/// files and a mid-episode scene in a few. Neither can be settled by the name.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-enum Claim {
-    Opening,
-    Ending,
-    Preview,
-    /// Reads like an opening, but only if the file has no real one and it is
-    /// the length of a theme song.
-    MaybeOpening,
-    /// Reads like credits, but only near the end of the file or at theme
-    /// length.
-    MaybeEnding,
-    Content,
-}
-
-/// How long an opening or ending theme runs.
-///
-/// Anime themes are ninety seconds by convention and rarely stray far. This is
-/// the corroboration for a name that could go either way: a chapter called
-/// `Intro` that runs eleven minutes is not a theme song, whatever it is called.
-const THEME_SECONDS: std::ops::RangeInclusive<f64> = 45.0..=150.0;
-
-/// Credits can run longer than a theme — a full cast roll over a still — so a
-/// chapter that only *reads* like an ending gets this much room when it sits at
-/// the end of the file.
-const CREDITS_SECONDS: std::ops::RangeInclusive<f64> = 30.0..=300.0;
-
-/// An opening that far into the file is not an opening. Cold opens run long in
-/// a first episode, so this is generous.
-const OPENING_BEFORE_SECONDS: f64 = 480.0;
-
-/// Where the last part of a file starts, as a fraction of it. A chapter that
-/// merely reads like credits is taken as credits past this point.
-const TAIL_FRACTION: f64 = 0.75;
-
-impl Claim {
-    /// Read a claim out of a chapter name.
-    ///
-    /// Matched on whole words from the front, not on substrings: `Operation
-    /// Briefing` starts with `op` and is not an opening, `Ending Note` is not
-    /// an ending, and skipping a viewer out of either is a mistake they cannot
-    /// undo without finding the seek bar. Leading numbering (`01 - OP`, `1.
-    /// Opening`) is stepped over first, because plenty of muxes carry it.
-    fn of(title: &str) -> Self {
-        // Japanese names appear verbatim in releases from JP sources, and they
-        // are unambiguous where the English ones are not. Checked before the
-        // word split, which only knows about ASCII and would find no words at
-        // all in a name written entirely in kana.
-        if title.contains("オープニング") {
-            return Self::Opening;
-        }
-        if title.contains("エンディング") {
-            return Self::Ending;
-        }
-        if title.contains("予告") {
-            return Self::Preview;
-        }
-
-        let words = words(title);
-        let words: Vec<&str> = words.iter().map(String::as_str).collect();
-        let Some((head, rest)) = words.split_first() else {
-            return Self::Content;
-        };
-        let second = rest.first().copied().unwrap_or_default();
-
-        match (*head, second) {
-            // Two-word forms first: the second word is what tells `next
-            // episode` from `next`, and `end credits` from `end`.
-            ("next", _) | ("nep", _) => Self::Preview,
-            ("end" | "ending" | "closing", "credits") => Self::Ending,
-            ("cast" | "staff", "roll" | "credits") => Self::Ending,
-            ("opening" | "op", "theme" | "song" | "credits") => Self::Opening,
-            ("ending" | "ed", "theme" | "song") => Self::Ending,
-
-            ("op" | "opening" | "openning" | "ncop", _) => Self::Opening,
-            ("ed" | "ending" | "nced" | "outro" | "endcard", _) => Self::Ending,
-            ("preview" | "pv" | "trailer" | "teaser" | "yokoku", _) => Self::Preview,
-
-            ("intro", _) => Self::MaybeOpening,
-            ("credits" | "closing" | "cast" | "staff", _) => Self::MaybeEnding,
-            _ => Self::Content,
-        }
-    }
-}
-
-/// A chapter name as lowercase words, with any leading numbering dropped.
-///
-/// `OP1` and `ED2` keep their tag and lose their number — the digit is part of
-/// the tag, not a word — while `02 - Opening` loses its leading `02` entirely.
-fn words(title: &str) -> Vec<String> {
-    let mut words: Vec<String> = title
-        .trim()
-        .to_ascii_lowercase()
-        .split(|c: char| !c.is_ascii_alphanumeric())
-        .filter(|word| !word.is_empty())
-        .map(|word| {
-            word.trim_end_matches(|c: char| c.is_ascii_digit())
-                .to_string()
-        })
-        .collect();
-    // A leading token that was *only* digits is numbering, not a name.
-    if words.first().is_some_and(String::is_empty) {
-        words.remove(0);
-    }
-    words.retain(|word| !word.is_empty());
-    words
-}
-
-/// The role of every chapter in a file, with the file's own shape taken into
-/// account.
-///
-/// This is the function to use. [`Chapter::role`] reads a name in isolation and
-/// cannot tell an opening called `Intro` from ten minutes of story called the
-/// same thing; here the other chapters and the running time settle it:
-///
-/// * a chapter that merely *reads* like an opening is one only when the file
-///   has no chapter that says so outright, it runs the length of a theme song,
-///   and it is near the front;
-/// * a chapter that reads like credits is the ending when it runs to about that
-///   length, or when it sits in the last quarter of the file.
-///
-/// Both rules fail *towards content*: not offering a skip costs a button, and
-/// skipping the viewer out of the story costs them the story.
-pub fn roles(chapters: &[Chapter], duration: Option<f64>) -> Vec<ChapterRole> {
-    let claims: Vec<Claim> = chapters
-        .iter()
-        .map(|chapter| Claim::of(chapter.title.as_deref().unwrap_or_default()))
-        .collect();
-    let has_real_opening = claims.contains(&Claim::Opening);
-
-    claims
-        .iter()
-        .enumerate()
-        .map(|(index, claim)| {
-            let length = chapter_end(chapters, index, duration)
-                .map(|end| end - chapters[index].start)
-                .filter(|length| *length > 0.0);
-            let start = chapters[index].start;
-
-            match claim {
-                Claim::Opening => ChapterRole::Opening,
-                Claim::Ending => ChapterRole::Ending,
-                Claim::Preview => ChapterRole::Preview,
-                Claim::MaybeOpening
-                    if !has_real_opening
-                        && start <= OPENING_BEFORE_SECONDS
-                        && length.is_some_and(|length| THEME_SECONDS.contains(&length)) =>
-                {
-                    ChapterRole::Opening
-                }
-                Claim::MaybeEnding
-                    if length.is_some_and(|length| CREDITS_SECONDS.contains(&length))
-                        || duration.is_some_and(|total| start >= total * TAIL_FRACTION) =>
-                {
-                    ChapterRole::Ending
-                }
-                _ => ChapterRole::Content,
-            }
-        })
-        .collect()
-}
-
-/// Where the run of chapters that ends the file — credits, a preview, and
-/// nothing the viewer would miss — begins.
-///
-/// **The suffix, not the last chapter.** A release that puts a Part C after the
-/// ending and a preview after that (Fullmetal Alchemist Brotherhood does,
-/// exactly once) must give up only the preview, or auto-advancing skips a scene
-/// that matters. Walking back from the end and stopping at the first chapter
-/// that is content is what expresses that: `… ED · Part C · Preview` yields the
-/// preview alone, while the ordinary `… ED · Preview` yields both.
-///
-/// `None` when the file ends on content, has no chapters, or is *entirely*
-/// skippable — the last of which is a mis-tagged file, not an episode that is
-/// all credits.
-pub fn credits_start(chapters: &[Chapter], roles: &[ChapterRole]) -> Option<f64> {
-    let first = roles
-        .iter()
-        .rposition(|role| !role.ends_the_episode())
-        .map(|last_content| last_content + 1)?;
-    if first >= chapters.len() {
-        return None;
-    }
-    Some(chapters[first].start)
-}
+pub use pstr_core::chapters::{
+    Chapter, ChapterRole, chapter_at, chapter_end, credits_start, roles,
+};
 
 /// Every chapter of the file mpv currently has open.
 pub(crate) fn read(mpv: &Mpv) -> Vec<Chapter> {
@@ -293,211 +32,3 @@ pub(crate) fn read(mpv: &Mpv) -> Vec<Chapter> {
         })
         .collect()
 }
-
-/// Where the chapter starting at `index` ends: the next one's start, or the end
-/// of the file.
-pub fn chapter_end(chapters: &[Chapter], index: usize, duration: Option<f64>) -> Option<f64> {
-    chapters
-        .get(index + 1)
-        .map(|next| next.start)
-        .or(duration)
-        .filter(|end| *end > 0.0)
-}
-
-/// The chapter a position falls in.
-///
-/// Linear rather than a binary search: a file has a dozen chapters, and this is
-/// called once a frame at most.
-pub fn chapter_at(chapters: &[Chapter], position: f64) -> Option<usize> {
-    chapters
-        .iter()
-        .rposition(|chapter| position + f64::EPSILON >= chapter.start)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    fn chapter(index: i64, title: &str, start: f64) -> Chapter {
-        Chapter {
-            index,
-            title: Some(title.to_string()),
-            start,
-        }
-    }
-
-    #[test]
-    fn the_names_releases_actually_use_are_recognised() {
-        for (name, claim) in [
-            ("OP", Claim::Opening),
-            ("Opening", Claim::Opening),
-            ("OP1 - Again", Claim::Opening),
-            ("02 - Opening", Claim::Opening),
-            ("Opening Song", Claim::Opening),
-            ("NCOP", Claim::Opening),
-            ("オープニング", Claim::Opening),
-            ("ED", Claim::Ending),
-            ("Ending 2", Claim::Ending),
-            ("End Credits", Claim::Ending),
-            ("Cast Roll", Claim::Ending),
-            ("Endcard", Claim::Ending),
-            ("エンディング", Claim::Ending),
-            ("Preview", Claim::Preview),
-            ("Next Episode", Claim::Preview),
-            ("Next Episode Preview", Claim::Preview),
-            ("予告", Claim::Preview),
-        ] {
-            assert_eq!(Claim::of(name), claim, "{name}");
-        }
-    }
-
-    #[test]
-    fn a_chapter_that_merely_starts_with_those_letters_is_not_one() {
-        // The reason this matches words and not prefixes: skipping the viewer
-        // out of "Operation Briefing" would be a bug they cannot undo without
-        // finding the seek bar.
-        for name in ["Operation Briefing", "Editor's cut", "Part A", "Part C", ""] {
-            assert_eq!(Claim::of(name), Claim::Content, "{name}");
-        }
-    }
-
-    /// The names that cannot be settled by reading them.
-    #[test]
-    fn an_ambiguous_name_is_not_decided_by_itself() {
-        assert_eq!(Claim::of("Intro"), Claim::MaybeOpening);
-        assert_eq!(Claim::of("Credits"), Claim::MaybeEnding);
-        assert_eq!(Claim::of("Cast"), Claim::MaybeEnding);
-        // And a chapter read in isolation never resolves to a skip.
-        assert_eq!(chapter(0, "Intro", 0.0).role(), ChapterRole::Content);
-    }
-
-    /// **The first episode of Oshi no Ko.** No opening, no ending — an eighty
-    /// minute episode that begins with a long `Intro` that is the story, and
-    /// ends with a cast scroll. Offering "skip opening" over the first ninety
-    /// seconds of *that* skips the beginning of the series.
-    #[test]
-    fn a_long_intro_is_the_episode_and_not_an_opening() {
-        let chapters = vec![
-            chapter(0, "Intro", 0.0),
-            chapter(1, "Part A", 700.0),
-            chapter(2, "Part B", 2400.0),
-            chapter(3, "Cast", 4680.0),
-        ];
-        let roles = roles(&chapters, Some(4800.0));
-        assert_eq!(
-            roles[0],
-            ChapterRole::Content,
-            "eleven minutes is not a theme"
-        );
-        assert_eq!(
-            roles[3],
-            ChapterRole::Ending,
-            "a cast roll at the end is one"
-        );
-        // Only the cast scroll is the tail; the episode is not skipped into.
-        assert_eq!(credits_start(&chapters, &roles), Some(4680.0));
-    }
-
-    /// The same name in the release that uses it for the theme song: ninety
-    /// seconds, near the front, and no other opening in the file.
-    #[test]
-    fn a_theme_length_intro_near_the_front_is_an_opening() {
-        let chapters = vec![
-            chapter(0, "Avant", 0.0),
-            chapter(1, "Intro", 90.0),
-            chapter(2, "Part A", 180.0),
-        ];
-        assert_eq!(roles(&chapters, Some(1440.0))[1], ChapterRole::Opening);
-
-        // …but not when the file already says which chapter the opening is.
-        let chapters = vec![
-            chapter(0, "Intro", 0.0),
-            chapter(1, "OP", 90.0),
-            chapter(2, "Part A", 180.0),
-        ];
-        let roles = roles(&chapters, Some(1440.0));
-        assert_eq!(roles[0], ChapterRole::Content);
-        assert_eq!(roles[1], ChapterRole::Opening);
-    }
-
-    /// The ordinary shape: the credits and the trailer for next week are one
-    /// run at the end, and the countdown starts where the credits do.
-    #[test]
-    fn the_tail_is_the_whole_run_of_credits_and_preview() {
-        let chapters = vec![
-            chapter(0, "OP", 0.0),
-            chapter(1, "Part A", 90.0),
-            chapter(2, "Part B", 700.0),
-            chapter(3, "ED", 1320.0),
-            chapter(4, "Preview", 1410.0),
-        ];
-        let roles = roles(&chapters, Some(1440.0));
-        assert_eq!(credits_start(&chapters, &roles), Some(1320.0));
-    }
-
-    /// **Episode 46 of Fullmetal Alchemist Brotherhood.** A Part C *after* the
-    /// ending, and the preview after that. Only the preview may be skipped —
-    /// treating everything from the ending on as tail would drop a scene.
-    #[test]
-    fn content_after_the_ending_keeps_the_ending_out_of_the_tail() {
-        let chapters = vec![
-            chapter(0, "Part A", 0.0),
-            chapter(1, "Part B", 700.0),
-            chapter(2, "ED", 1260.0),
-            chapter(3, "Part C", 1350.0),
-            chapter(4, "Preview", 1400.0),
-        ];
-        let roles = roles(&chapters, Some(1440.0));
-        assert_eq!(roles[2], ChapterRole::Ending, "it is still an ending");
-        assert_eq!(credits_start(&chapters, &roles), Some(1400.0));
-    }
-
-    /// A file that ends on the story has no tail at all, and one with no
-    /// chapters has nothing to read.
-    #[test]
-    fn a_file_that_ends_on_content_has_no_tail() {
-        let chapters = vec![chapter(0, "OP", 0.0), chapter(1, "Part A", 90.0)];
-        let roles = roles(&chapters, Some(1440.0));
-        assert_eq!(credits_start(&chapters, &roles), None);
-        assert_eq!(credits_start(&[], &[]), None);
-
-        // Everything skippable is a mis-tagged file, not an episode that is
-        // entirely credits: auto-advancing out of it at second zero would be
-        // worse than doing nothing.
-        let chapters = vec![chapter(0, "OP", 0.0), chapter(1, "ED", 90.0)];
-        let roles = vec![ChapterRole::Ending, ChapterRole::Ending];
-        assert_eq!(credits_start(&chapters, &roles), None);
-    }
-
-    #[test]
-    fn a_position_lands_in_the_chapter_that_contains_it() {
-        let chapters = vec![
-            chapter(0, "Intro", 0.0),
-            chapter(1, "OP", 24.0),
-            chapter(2, "Part A", 114.0),
-        ];
-        assert_eq!(chapter_at(&chapters, 0.0), Some(0));
-        assert_eq!(chapter_at(&chapters, 23.9), Some(0));
-        // Exactly on a boundary belongs to the chapter that starts there,
-        // which is what makes "skip" land *out* of the opening rather than at
-        // its last frame.
-        assert_eq!(chapter_at(&chapters, 24.0), Some(1));
-        assert_eq!(chapter_at(&chapters, 3000.0), Some(2));
-    }
-
-    #[test]
-    fn a_chapter_before_the_first_one_starts_is_in_no_chapter() {
-        let chapters = vec![chapter(0, "OP", 24.0)];
-        assert_eq!(chapter_at(&chapters, 0.0), None);
-    }
-
-    #[test]
-    fn the_last_chapter_ends_where_the_file_does() {
-        let chapters = vec![chapter(0, "OP", 0.0), chapter(1, "Part A", 90.0)];
-        assert_eq!(chapter_end(&chapters, 0, Some(1440.0)), Some(90.0));
-        assert_eq!(chapter_end(&chapters, 1, Some(1440.0)), Some(1440.0));
-        // No duration yet and nothing after it: there is nowhere to skip to,
-        // and a button that seeks to zero would be worse than no button.
-        assert_eq!(chapter_end(&chapters, 1, None), None);
-    }
-}

crates/pstr-stream/src/source.rs

@@ -165,6 +165,10 @@ impl StreamSource {
             uid: uid.clone(),
         };
         if let Some(stream) = self.inner.lock().pop(&key) {
+            // Before the ring is cleared, not after: a prefetch still in flight
+            // would otherwise re-insert into the ring this just emptied, and
+            // keep downloading for a stream nobody is reading.
+            stream.cancel_read_ahead();
             self.inner.ring.forget(uid, stream.revision_id());
         }
     }

crates/pstr-stream/src/stream.rs

@@ -259,20 +259,12 @@ impl VideoStream {
     /// wants an aborted block simply refetches it — the single-flight entry is
     /// released by its guard when the task is dropped, so nothing waits on a
     /// call that will never finish.
-    fn cancel_read_ahead(&self) {
-        let tasks = std::mem::take(&mut *self.inner.tasks());
-        let mut cancelled = 0_u64;
-        for task in tasks {
-            if !task.is_finished() {
-                task.abort();
-                cancelled += 1;
-            }
-        }
-        if cancelled > 0 {
-            self.inner
-                .readahead_cancelled
-                .fetch_add(cancelled, Ordering::Relaxed);
-        }
+    ///
+    /// Public because a seek is not the only reason to stop speculating: a
+    /// stream nobody is reading any more should not keep spending a phone's
+    /// data plan, which is what [`crate::StreamSource::close`] uses this for.
+    pub fn cancel_read_ahead(&self) {
+        self.inner.cancel_read_ahead();
     }
 
     /// Queue the next few blocks after `from`.
@@ -300,10 +292,15 @@ impl VideoStream {
             };
 
             inner.readahead_started.fetch_add(1, Ordering::Relaxed);
-            let spawned = Arc::clone(inner);
+            // Weak, so that a queue of prefetches cannot keep the stream they
+            // are speculating for alive — see `impl Drop for Inner`.
+            let spawned = Arc::downgrade(inner);
             let task = tokio::spawn(async move {
                 let _slot = slot;
-                if let Err(e) = block_at(spawned, index).await {
+                let Some(inner) = spawned.upgrade() else {
+                    return;
+                };
+                if let Err(e) = block_at(inner, index).await {
                     tracing::debug!(index, error = %e, "read-ahead block failed");
                 }
             });
@@ -352,6 +349,39 @@ impl Inner {
             .lock()
             .unwrap_or_else(PoisonError::into_inner)
     }
+
+    fn cancel_read_ahead(&self) {
+        let tasks = std::mem::take(&mut *self.tasks());
+        let mut cancelled = 0_u64;
+        for task in tasks {
+            if !task.is_finished() {
+                task.abort();
+                cancelled += 1;
+            }
+        }
+        if cancelled > 0 {
+            self.readahead_cancelled
+                .fetch_add(cancelled, Ordering::Relaxed);
+        }
+    }
+}
+
+/// A stream nobody holds any more stops speculating.
+///
+/// Read-ahead tasks hold a [`Weak`] rather than an [`Arc`], so their existence
+/// does not keep this alive and this can run while they are still in flight —
+/// which is the point. Without it, closing the player mid-episode leaves up to a
+/// full read-ahead window downloading for a stream nobody is watching, and those
+/// blocks then evict the ones the *next* stream has already fetched.
+///
+/// A prefetch that has already upgraded its handle keeps this alive for the one
+/// block it is fetching. That block is the residue; the window behind it is not.
+impl Drop for Inner {
+    fn drop(&mut self) {
+        for task in std::mem::take(&mut *self.tasks()) {
+            task.abort();
+        }
+    }
 }
 
 /// Resolve one block: memory, then disk, then the network.
@@ -791,6 +821,31 @@ mod tests {
         );
     }
 
+    /// Closing the player mid-episode must stop the speculation too. On a phone
+    /// on cellular this is up to a full read-ahead window downloaded for a
+    /// stream nobody is watching — and those blocks then evict the ones the next
+    /// stream has already fetched.
+    #[tokio::test]
+    async fn abandoning_a_stream_stops_its_read_ahead() {
+        let fake = Fake::slow(&[1024 * 1024; 200], std::time::Duration::from_millis(200));
+        let stream = stream_over(Arc::clone(&fake), 4);
+
+        stream.read_range(0, 1_000).await.unwrap();
+        tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+        assert!(stream.stats().readahead_blocks > 0, "nothing to cancel");
+        let started = fake.fetches();
+
+        drop(stream);
+        // Long enough that every prefetch in flight would have completed.
+        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+
+        assert!(
+            fake.fetches() <= started + 1,
+            "read-ahead outlived the stream: {} fetches after {started}",
+            fake.fetches(),
+        );
+    }
+
     /// And the mirror image: steady playback must not keep throwing its own
     /// read-ahead away.
     #[tokio::test]

docs/ANDROID.md

@@ -43,9 +43,32 @@ adb install -r android/app/build/outputs/apk/debug/app-debug.apk
 ```
 
 Before submitting Android work, run the Rust workspace gate from the repository
-root and `bash scripts/build-android.sh check`. Test phone and tablet layouts,
-rotation, process recreation, playback/background controls, Picture-in-Picture,
-download cancellation/resume, and an offline launch with networking disabled.
+root, then:
+
+```bash
+bash scripts/build-android.sh check          # ktlint, Android lint, host tests
+bash scripts/android-acceptance.sh --release # the on-device matrix, minified APK
+```
+
+`check` needs no device. Run the matrix with `--release` where you can: it
+installs the signed minified APK and runs instrumentation against it, which is
+the only path that exercises R8 — the step that has broken this app five distinct
+ways that a debug build cannot reproduce. Without the `ANDROID_RELEASE_*`
+variables below, drop `--release` and the debug APK is used instead. The matrix — phone and tablet layouts, rotation,
+process recreation, playback and background controls, Picture-in-Picture,
+download cancellation/resume, and an offline launch with networking disabled —
+is `scripts/android-acceptance.sh`; `--list` prints every case and what it
+needs, and `PSTR_ACCEPTANCE_ONLY=name` runs one. Five cases need a real share,
+given as `PSTR_ACCEPTANCE_SHARE_URL` and `PSTR_ACCEPTANCE_SHARE_PASSWORD`; they
+reach the device as instrumentation arguments and are stored nowhere. Without
+them those cases report `skip`. `picture-in-picture` is still `pending`, so the
+run tells you the matrix is incomplete — but no longer because of B40, which is
+fixed; the case now just needs writing. `docs/TESTING.md` has the layer-by-layer
+detail, including why lint runs against a baseline.
+
+Requires JDK 17. `build-android.sh` locates it, because a newer JVM does not
+fail with a version message — the Kotlin compiler throws
+`IllegalArgumentException: 26.0.2` from an IntelliJ version parser.
 
 ## Release Signing
 

docs/DESIGN-TOKENS.md

@@ -0,0 +1,108 @@
+# Design tokens
+
+What the desktop and Android clients agree on, and where each one keeps its copy.
+
+Colour needs no spec: `pstr_core::appearance` resolves one `Palette` and both
+clients read it, so a flavour is right in both places or wrong in both. The rest
+of the token set has no such bridge — Compose cannot consume a Rust constant, and
+type and shape do not survive a round trip through `PaletteRecord` — so this file
+is the contract, and each side's copy is asserted against it by a test.
+
+| Token | Owner | Android's copy | Pinned by |
+|---|---|---|---|
+| Colour roles | `pstr_core::appearance::Palette` | `ui/theme/Theme.kt` `schemeOf` | `SchemeRolesTest` |
+| Type ramp | `pstr_app::theme::Role` | `ui/theme/Type.kt` | `TypeRampTest` |
+| Corner radius | `pstr-app` `ui/mod.rs` | `ui/theme/Shape.kt` | `TypeRampTest` |
+| Gradient rule | `Palette::resolve` | — (derived, see below) | `appearance.rs` tests |
+| Depth | `pstr_app::theme::{tile_shadow, bar_shadow}` | Material elevation | — |
+| Motion | `Context::animate_*` | Compose defaults | — |
+
+## Type
+
+Nine rungs. The desktop names them; Android restates them because Material's own
+scale is a different one (`displayLarge` is 57sp, which is a size for a lock
+screen and not for anything in a library grid).
+
+| Role | Size | What it is |
+|---|---|---|
+| Display | 26 | the name of the thing you are looking at, once per page |
+| Title | 20 | an empty state, or a page heading with no display line |
+| Heading | 18 | the brand in the nav bar; a dialog's heading |
+| Section | 17 | a run of content under a rule |
+| Subhead | 15 | a row that groups the rows under it — a season header |
+| Body | 14 | everything that is prose |
+| Label | 13 | the text on a small control |
+| Caption | 12 | context rather than content: counts, sizes, errors under a field |
+| Micro | 11 | the smallest thing that stays legible — a badge over artwork |
+
+Weight and leading are each side's own: egui has one weight, and Compose derives
+line height as 1.35 × size rather than naming it nine more times.
+
+Both clients point their framework's *default* styles at the ramp — egui's five
+`TextStyle`s, Compose's fifteen — so a stock widget nobody restyled still lands
+on it. Material 1.4 additionally carries an `Emphasized` copy of all fifteen
+styles for its expressive components; those are `internal`, cannot be set from
+this module, and keep Material's sizes. Nothing in the app draws with them.
+
+## Shape
+
+**Radius 8** for everything either client paints: cards, buttons, the tab pill,
+progress bars, dialogs. **4** for a badge over artwork. **16** for an Android
+bottom sheet, which has no desktop counterpart.
+
+Two traps, both Android's:
+
+- Material's default shape ramp is 4 / 8 / 12 / 16 / 28, so an unstyled screen
+  puts a 28dp sheet beside a 12dp card beside a fully-round button.
+- Material's *buttons* read their own shape token (`CornerFull`), not
+  `MaterialTheme.shapes`. Handing them a shape is what
+  `AccentButton` / `TonalButton` / `EdgedButton` / `QuietButton`
+  (`ui/theme/Accent.kt`) are for. Use those, not Material's, at a new call site.
+
+## The accent, and what `gradients` means
+
+The accent is the **only strong colour in the window**. Something wearing it is
+something to interact with; nothing wears it for decoration. Neither client
+draws an elevation tint (`surfaceTint` is transparent on Android) — a surface
+that is faintly accent-coloured because it happens to be raised breaks that rule.
+
+Where the accent is a ramp rather than a flat fill, in both clients:
+
+- the primary button
+- the seek bar's spent side
+- the progress bar under a tile and under an episode row
+- the selected navigation pill *(desktop only — see below)*
+
+Neither client branches on the stored `gradients` flag to decide this.
+`Palette::resolve` sets `accent_alt` equal to `accent` when the flag is off, so a
+two-stop brush collapses to a flat fill by itself. That is deliberate: a flag
+read in two places is a flag that will eventually mean two things, which is
+exactly what [B52](BUGS.md#b52--paint-the-accent-as-a-gradient-did-nothing-on-android)
+was.
+
+Known divergences, both Android's, both because the component takes a `Color`
+and offers no slot to draw into:
+
+- The navigation pill is solid `primary` rather than a ramp.
+- A download in flight is solid `tertiary` by choice, not by limitation: it is
+  drawn directly under the watch-progress bar of the same row, and two ramps in
+  the same colour two pixels apart say nothing.
+
+## Depth and motion
+
+The desktop casts shadows from `theme::tile_shadow` / `theme::bar_shadow`, which
+**halve on a light flavour** — the same black that separates a card from a dark
+page is a smudge on a near-white one. Android gets Material's elevation, which
+already adapts. Neither uses a tint to say "raised".
+
+Transitions on the desktop go through `Context::animate_*`: wall-clock driven,
+frame-rate independent, no state held by the caller. Durations in use are 0.05 s
+for a press, 0.10–0.12 s for a hover, 0.16 s for the tab pill's travel and 0.22 s
+for artwork arriving. Compose's defaults are close enough that nothing here
+overrides them.
+
+## Adding a token
+
+Name it in the owning client first, restate it on the other side, and extend the
+test that pins the copy. A token that lives in only one place is not a token —
+it is a literal with a comment.

docs/DEVELOPMENT.md

@@ -170,6 +170,38 @@ reads an external subtitle through the same protocol); the work is in
   rustls. Separately a browser cannot reach the Proton API at all (CORS) without
   a proxy server, which the fat-client decision rules out.
 
+- **One palette, one type ramp, one shape radius — named, not repeated.**
+  `pstr_core::appearance` already settled colour for both clients;
+  `pstr_app::theme::Role` settles size the same way. A `.size(17.0)` at a call
+  site is not a scale, it is one of forty independent decisions that happen to
+  sit near each other, and it is why the two clients read as different apps even
+  when their colours agreed. Anything new asks for a role.
+- **Depth and motion are the theme's, not the widget's.** Shadows come from
+  `theme::tile_shadow` / `theme::bar_shadow`, which halve themselves on a light
+  flavour — the same black that separates a card from a dark page is a smudge on
+  a near-white one. Transitions go through `Context::animate_*`, which is driven
+  by wall-clock time and keeps no state of its own, so a hover that fades needs
+  no field anywhere.
+- **The grid flexes; `CARD_WIDTH` is a minimum.** `ui::columns` hands back the
+  column count *and* the width they should be drawn at. Dividing by the constant
+  and flooring leaves up to a full card of dead space at the right of every row.
+- **Android copies the ramp; a test says so.** `ui/theme/Type.kt` and
+  `ui/theme/Shape.kt` are `Role` and radius 8 restated for Compose, because
+  Material's own defaults are a different scale (57sp displays, a five-step
+  corner ramp ending in a fully-round button) and there is no bridge to resolve
+  type the way `appearance` resolves colour. `TypeRampTest` names all fifteen
+  Material styles and fails on a sixteenth, so the copy cannot drift quietly.
+  Note that Material's filled buttons read their own shape token rather than
+  `MaterialTheme.shapes` — that is what `AccentButton`/`TonalButton`/
+  `EdgedButton`/`QuietButton` in `ui/theme/Accent.kt` exist for, and new call
+  sites should use them rather than Material's directly.
+- **The gradient toggle is not read where the gradient is drawn.**
+  `Palette::resolve` sets `accent_alt` equal to `accent` when gradients are off,
+  so a two-stop brush collapses to a flat fill on its own. Both clients rely on
+  that instead of branching on the flag, which is what keeps them from
+  disagreeing about what the stored setting means (see
+  [B52](BUGS.md#b52--paint-the-accent-as-a-gradient-did-nothing-on-android)).
+
 ## Traps
 
 - **Block sizes are not uniform.** Always `RevisionReader::block_sizes()`; never

docs/TESTING.md

@@ -170,6 +170,123 @@ one failure the smoke test can see but a short run cannot.
 `Cannot load libcuda.so.1` on stderr is mpv's `hwdec=auto-safe` probe declining a
 backend. Not an error.
 
+## Android
+
+Three layers, and the split is deliberate: anything that can run on a host does,
+anything that needs Android's own implementations runs on a device, and anything
+that needs a viewer's eyes is a scripted case rather than a paragraph in a
+checklist.
+
+```bash
+bash scripts/build-android.sh check            # ktlint, Android lint, host tests
+bash scripts/android-acceptance.sh --list      # what the device suite covers
+bash scripts/android-acceptance.sh             # debug APK, one attached device
+bash scripts/android-acceptance.sh --release   # the signed minified APK that ships
+```
+
+Prefer `--release`. R8 is the step that has actually broken this app, in five
+distinct ways no debug run could reproduce (B44), and the release path is the
+only one that exercises it. It needs the four `ANDROID_RELEASE_*` signing
+variables from `docs/ANDROID.md` and a release APK built beforehand.
+
+`check` needs no device and no account. It picks JDK 17 itself — a newer JVM
+does not report a version error, it throws `IllegalArgumentException: 26.0.2` out
+of a Kotlin version parser, which reads as a broken build.
+
+**Host tests** (`app/src/test`) run under Robolectric, pinned to API 34 because
+Robolectric ships no image for the app's targetSdk of 36, and against a plain
+`Application` because the real one calls `System.loadLibrary("pstr_android")`,
+which has no host build. What is pinned today is `DownloadStateStore`: the JSON
+round trip, a corrupt row being skipped rather than failing the whole list, and
+the two decode fallbacks that are easy to get backwards — a missing `label`
+falling back to the link id, and a blank `error` reading as *no* error rather
+than as a permanently failed download.
+
+The other two host tests pin the half of `docs/DESIGN-TOKENS.md` that no bridge
+enforces. `SchemeRolesTest` sweeps `ColorScheme` reflectively and fails on any
+role carrying a value the palette did not supply — including a role a future
+Material version adds, the day the dependency moves. `TypeRampTest` names all
+fifteen Material text styles against the shared ramp and fails on a sixteenth,
+and checks the corner radius the desktop draws at. Both are lists of the *other*
+client's decisions, so a change to `pstr_app::theme::Role` that nobody carried
+across fails here rather than being noticed in a screenshot.
+
+**Instrumentation tests** (`app/src/androidTest`) are the things with no host
+equivalent:
+
+- **`KeystoreSecretStore`** — round trip including non-ASCII, that the stored
+  form is not the plaintext, and that **every write draws a fresh IV** (GCM under
+  IV reuse leaks the XOR of two plaintexts). Then the failure modes, which are
+  the point: a tampered payload, a truncated one, and a *destroyed key* — the
+  lockscreen-change and device-restore case — must fail the read without taking
+  the process down, and the store must still accept a re-entered secret.
+- **`UniFfiBoundaryTest`** — the first thing to cross the FFI on real hardware,
+  deliberately offline. It proves the ABI, the generated bindings, the callback
+  interface and the SQLite open, so a failure here with a green Rust workspace
+  means packaging: a missing ABI in `jniLibs`, a stale binding, or an R8 rule.
+  Under `--release` this is the direct evidence that R8 does not break the FFI —
+  the question `proguard-rules.pro` exists to answer, and which nothing else in
+  the tree checks.
+- **`DownloadCoordinatorInstrumentedTest`** — what reaches WorkManager: the
+  unique-work identity pause and resume depend on, cancel-by-share not touching
+  another share, and the exact tag set, since tags are persisted unencrypted and
+  pinning them is what makes an accidental addition visible in review.
+
+**The device suite** (`scripts/android-acceptance.sh`) is the matrix
+`docs/ANDROID.md` requires before Android work is submitted. Cases carry one of
+three dispositions, and the third is the one to read:
+
+| | meaning |
+|---|---|
+| `xfail` | a known-open bug in `docs/BUGS.md`. Failing is expected; **passing fails the run**, because the bug is fixed and the case should be promoted |
+| `pending` | specified but not implemented. Never passes, and the summary reports the matrix as incomplete until it is gone |
+| `skip` | needs a share that was not configured |
+
+Today `process-recreation` is `xfail` against B35, and `picture-in-picture` is
+`pending` against B40 — asserting today's behaviour would encode the bug rather
+than catch it. **The matrix is not complete, and the runner says so on every
+run.**
+
+The five live cases need a share, given as environment variables that reach the
+device as instrumentation arguments and are written nowhere:
+
+```bash
+PSTR_ACCEPTANCE_SHARE_URL='https://drive.proton.me/urls/...#...' \
+PSTR_ACCEPTANCE_SHARE_PASSWORD='...' \
+  bash scripts/android-acceptance.sh --release
+```
+
+Without them those cases report `skip`. They are read-only against the share —
+nothing uploads, renames or deletes anything remote — but `download-cancel-resume`
+does pull real bytes, so expect traffic. `playback` is the one that matters most:
+it asserts libmpv's position advances, which only happens if decrypted bytes
+crossed block storage, the Rust C ABI and the JNI adapter into the decoder. All
+five share a single instrumentation run, because each one re-crawls the share
+from an empty catalog otherwise — about six minutes apiece.
+
+Lint runs against a **baseline**, which is not an exemption: every entry in
+`android/app/lint-baseline.xml` maps to an open bug — the four
+SharedPreferences `commit()` calls are B20, the PiP one is B40 — and the file
+should get shorter as those land. Regenerate it with `gradlew updateLintBaseline`
+after a fix, never to silence something unrelated. ktlint runs a narrow ruleset
+for the same reason: the full standard set reports ~540 findings on this tree,
+almost all line-wrapping preference, and a mechanical reformat would bury the
+changes that matter. `android/.editorconfig` says which rules are on and why.
+
+Two things about the release path worth knowing before they surprise you. The
+lint baseline is generated by the `lint` task, and `lintVitalRelease` reports it
+as created for a different variant, so the release lint run is not actually
+baseline-checked — it currently finds nothing either way, but do not read a green
+`lintVitalRelease` as the baseline holding. And `proguard-instrumentation.pro`
+holds keeps that exist *only* so the instrumentation APK can link against the
+minified app; they ship. The file explains each one and the fidelity it costs.
+Adding to it is the normal response to a `NoSuchMethodError` or
+`NoClassDefFoundError` that appears only under `--release`.
+
+Cases that start the app wake and unlock the screen first, and a device behind a
+PIN reports `skip` rather than a misleading failure — a dark screen has no
+resumed activity, which looks exactly like a crashed app.
+
 ## SDK-side
 
 The streaming surface this app depends on is tested in `../proton-sdk-rs`:

packaging/PKGBUILD

@@ -14,7 +14,7 @@
 #     builds from the registry alone.
 
 pkgname=proton-stream
-pkgver=0.2.0
+pkgver=0.4.1
 pkgrel=1
 pkgdesc="Netflix-style desktop client for Proton Drive public links: browse and stream a share"
 arch=('x86_64')

scripts/android-acceptance.py

@@ -0,0 +1,867 @@
+#!/usr/bin/env python3
+"""On-device acceptance for the Android client.
+
+Driven by scripts/android-acceptance.sh. Every case states what it observes and
+why it matters; a case that cannot run says so rather than passing quietly.
+
+Cases carry one of three dispositions:
+
+  normal   expected to pass; a failure fails the run
+  xfail    a known-open bug in docs/BUGS.md. Failing is expected and does not
+           fail the run; *passing* fails it, because the bug is fixed and the
+           case should be promoted
+  pending  the case is specified but not implemented. It never passes, and the
+           summary reports the matrix as incomplete until it is gone
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+import zipfile
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+# The debug build carries an applicationId suffix, so the installed package and
+# the activity's class name do not share a prefix. Keeping them apart matters:
+# `am start -n <pkg>/.MainActivity` expands the leading dot against the *package*
+# argument, which on a debug build names a class that does not exist.
+APPLICATION_ID = "io.narl.protonstream"
+MAIN_ACTIVITY_CLASS = "io.narl.protonstream.MainActivity"
+
+# Resolved in main() from --package/--apk; the release build has no suffix.
+PACKAGE = f"{APPLICATION_ID}.debug"
+
+LIVE_TEST_CLASS = "io.narl.protonstream.live.LiveShareTest"
+
+DEBUG_APK = REPO_ROOT / "android/app/build/outputs/apk/debug/app-debug.apk"
+RELEASE_APK = REPO_ROOT / "android/app/build/outputs/apk/release/app-release.apk"
+
+
+class CaseError(Exception):
+    """A case failed on an assertion it makes about the device."""
+
+
+class CaseSkipped(Exception):
+    """A case cannot run here — missing configuration, wrong device."""
+
+
+class CasePending(Exception):
+    """A case is specified but not implemented."""
+
+
+@dataclass
+class Case:
+    name: str
+    what: str
+    run: Callable[["Device", "Options"], None]
+    xfail: str | None = None
+    needs_share: bool = False
+
+
+REGISTRY: list[Case] = []
+
+
+def case(name: str, what: str, xfail: str | None = None, needs_share: bool = False):
+    def register(fn):
+        REGISTRY.append(Case(name=name, what=what, run=fn, xfail=xfail, needs_share=needs_share))
+        return fn
+
+    return register
+
+
+# --------------------------------------------------------------------------
+# device
+
+
+class Device:
+    def __init__(self, serial: str | None, timeout: int):
+        self.serial = serial
+        self.timeout = timeout
+        self._base_apk: Path | None = None
+
+    def _adb(self, *args: str) -> list[str]:
+        prefix = ["adb"]
+        if self.serial:
+            prefix += ["-s", self.serial]
+        return prefix + list(args)
+
+    def run(self, *args: str, check: bool = True, timeout: int | None = None) -> str:
+        proc = subprocess.run(
+            self._adb(*args),
+            capture_output=True,
+            text=True,
+            timeout=timeout or self.timeout,
+        )
+        if check and proc.returncode != 0:
+            raise CaseError(
+                f"adb {' '.join(args)} failed ({proc.returncode}): "
+                f"{(proc.stderr or proc.stdout).strip()}"
+            )
+        return proc.stdout
+
+    def shell(self, command: str, check: bool = True, timeout: int | None = None) -> str:
+        return self.run("shell", command, check=check, timeout=timeout)
+
+    def prop(self, name: str) -> str:
+        return self.shell(f"getprop {name}").strip()
+
+    @property
+    def api_level(self) -> int:
+        return int(self.prop("ro.build.version.sdk") or 0)
+
+    @property
+    def abi(self) -> str:
+        return self.prop("ro.product.cpu.abi")
+
+    def pid(self) -> int | None:
+        out = self.shell(f"pidof {PACKAGE}", check=False).strip()
+        return int(out.split()[0]) if out else None
+
+    def is_installed(self) -> bool:
+        return bool(self.shell(f"pm list packages {PACKAGE}", check=False).strip())
+
+    def wake(self) -> None:
+        # A dark or locked screen has no resumed activity, so every case that
+        # starts the app would fail for a reason that has nothing to do with the
+        # app. `dismiss-keyguard` clears a swipe lock; a PIN or pattern needs a
+        # human, which is what `assert_unlocked` reports.
+        self.shell("input keyevent KEYCODE_WAKEUP", check=False)
+        self.shell("wm dismiss-keyguard", check=False)
+        time.sleep(0.5)
+
+    def keyguard_locked(self) -> bool:
+        out = self.shell("dumpsys window", check=False)
+        match = re.search(r"mDreamingLockscreen=(\w+)", out)
+        return bool(match and match.group(1) == "true")
+
+    def launch(self) -> None:
+        self.wake()
+        self.shell(f"am start -W -n {PACKAGE}/{MAIN_ACTIVITY_CLASS}")
+
+    def force_stop(self) -> None:
+        self.shell(f"am force-stop {PACKAGE}", check=False)
+
+    def clear_logcat(self) -> None:
+        self.run("logcat", "-c", check=False)
+
+    def logcat_since_clear(self) -> str:
+        return self.run("logcat", "-d", check=False)
+
+    def wait_for_process(self, seconds: float = 15.0) -> int:
+        deadline = time.time() + seconds
+        while time.time() < deadline:
+            pid = self.pid()
+            if pid:
+                return pid
+            time.sleep(0.25)
+        raise CaseError(f"{PACKAGE} did not start within {seconds:.0f}s")
+
+    def pull_base_apk(self) -> Path:
+        # Pulled from the device rather than read from build/outputs, so the
+        # case reports on what is actually installed even under --no-install.
+        if self._base_apk is None:
+            paths = [
+                line.removeprefix("package:").strip()
+                for line in self.shell(f"pm path {PACKAGE}").splitlines()
+                if line.startswith("package:")
+            ]
+            base = next((path for path in paths if path.endswith("base.apk")), None)
+            if base is None:
+                raise CaseError(f"pm path reported no base.apk for {PACKAGE}")
+            local = Path(tempfile.mkdtemp(prefix="pstr-acceptance-")) / "base.apk"
+            self.run("pull", base, str(local), timeout=600)
+            if not local.is_file():
+                raise CaseError(f"could not pull {base} off the device")
+            self._base_apk = local
+        return self._base_apk
+
+    def resumed_activity(self) -> str:
+        out = self.shell("dumpsys activity activities | grep -E 'mResumedActivity|topResumedActivity'", check=False)
+        return out.strip()
+
+
+def assert_no_crash(device: Device) -> None:
+    # Every check here is scoped to this app's own process. logcat is
+    # system-wide, and a case that changes global state provokes crashes in
+    # unrelated software: `offline-launch` toggles airplane mode, which reliably
+    # kills Google Play services with a FATAL EXCEPTION that has nothing to do
+    # with us. Attributing that to the app under test makes the suite lie.
+    lines = device.logcat_since_clear().splitlines()
+    owner = re.compile(r"\bProcess:\s*" + re.escape(PACKAGE) + r"\b")
+    for index, line in enumerate(lines):
+        if re.search(r"\bANR in " + re.escape(PACKAGE), line):
+            raise CaseError(f"ANR in logcat:\n" + "\n".join(lines[index : index + 20]))
+        if re.search(r"FATAL EXCEPTION", line, re.I):
+            # The runtime prints `Process: <package>, PID: <n>` on the line
+            # right after the FATAL EXCEPTION header.
+            if any(owner.search(nxt) for nxt in lines[index : index + 4]):
+                raise CaseError("crash in logcat:\n" + "\n".join(lines[index : index + 30]))
+        if "Fatal signal" in line:
+            # A native crash names the process in the tombstone header a few
+            # lines below, as `>>> <package> <<<`.
+            window = lines[index : index + 12]
+            if any(f">>> {PACKAGE} <<<" in nxt for nxt in window):
+                raise CaseError("native crash in logcat:\n" + "\n".join(window))
+
+
+# --------------------------------------------------------------------------
+# cases
+
+
+@case("install", "the app is installed and its version is the workspace version")
+def _install(device: Device, options: "Options") -> None:
+    if not device.is_installed():
+        raise CaseError(f"{PACKAGE} is not installed; run without --no-install")
+    dumped = device.shell(f"dumpsys package {PACKAGE} | grep versionName")
+    match = re.search(r"versionName=([^\s]+)", dumped)
+    if not match:
+        raise CaseError("dumpsys reported no versionName")
+    installed = match.group(1).removesuffix("-debug")
+    cargo = (REPO_ROOT / "Cargo.toml").read_text()
+    expected = re.search(r'(?m)^version\s*=\s*"([^"]+)"', cargo)
+    if not expected:
+        raise CaseError("no workspace version in Cargo.toml")
+    if installed != expected.group(1):
+        raise CaseError(
+            f"installed {installed} but the workspace is {expected.group(1)}; "
+            "the APK is stale — rebuild before trusting this run"
+        )
+
+
+@case("native-libraries", "every native library the app dlopens is packaged for this ABI")
+def _native_libraries(device: Device, options: "Options") -> None:
+    # The three that must be there: the Rust bridge, the GPL libmpv, and the
+    # JNI/EGL adapter between them. A missing one is a packaging fault that only
+    # shows up when the viewer presses play.
+    #
+    # The APK is the authority, not the on-device `lib/` directory. With
+    # `useLegacyPackaging = false` the installer never extracts anything — the
+    # libraries are mapped straight out of the (uncompressed, page-aligned) APK,
+    # so that directory is legitimately empty on a healthy install. Reading
+    # /proc/<pid>/maps would be the direct runtime proof, but it is unreadable
+    # for another app's process without root.
+    apk = device.pull_base_apk()
+    try:
+        with zipfile.ZipFile(apk) as archive:
+            entries = archive.namelist()
+    except zipfile.BadZipFile as error:
+        raise CaseError(f"the installed APK is not readable as a zip: {error}") from None
+
+    abis = sorted({name.split("/")[1] for name in entries if name.startswith("lib/") and "/" in name[4:]})
+    if device.abi not in abis:
+        raise CaseError(
+            f"the device is {device.abi} but the APK packages only {', '.join(abis) or '(no ABI)'}"
+        )
+    packaged = {name.rsplit("/", 1)[1] for name in entries if name.startswith(f"lib/{device.abi}/")}
+    missing = [
+        name
+        for name in ("libpstr_android.so", "libmpv.so", "libpstr_mpv.so")
+        if name not in packaged
+    ]
+    if missing:
+        raise CaseError(
+            f"not packaged for {device.abi}: {', '.join(missing)}\n"
+            f"saw: {', '.join(sorted(packaged)) or '(nothing)'}"
+        )
+
+
+@case("manifest-hardening", "backup stays closed and no unexpected component is exported")
+def _manifest_hardening(device: Device, options: "Options") -> None:
+    dumped = device.shell(f"dumpsys package {PACKAGE}")
+    flags = re.search(r"flags=\[([^\]]*)\]", dumped)
+    if flags and "ALLOW_BACKUP" in flags.group(1):
+        raise CaseError(
+            "ALLOW_BACKUP is set: share fragments and link passwords would leave the device"
+        )
+    # Only MainActivity may be exported. Both services are internal, and anything
+    # that can reach them inherits the daemon's authenticated session.
+    exported = re.findall(r"^\s+(\S+/\S+)\s+filter", dumped, re.M)
+    unexpected = [name for name in exported if "MainActivity" not in name]
+    if unexpected:
+        raise CaseError(f"unexpectedly exported components: {', '.join(sorted(set(unexpected)))}")
+
+
+@case("cold-start", "a cold launch reaches a resumed activity without a crash")
+def _cold_start(device: Device, options: "Options") -> None:
+    device.force_stop()
+    device.clear_logcat()
+    device.launch()
+    device.wait_for_process()
+    time.sleep(2.0)
+    assert_no_crash(device)
+    resumed = device.resumed_activity()
+    if APPLICATION_ID not in resumed:
+        if device.keyguard_locked():
+            raise CaseSkipped("the device is locked and needs a PIN; unlock it and run again")
+        raise CaseError(f"no resumed activity for the app: {resumed or '(dumpsys reported none)'}")
+
+
+@case("rotation", "rotating does not recreate the process or drop the activity")
+def _rotation(device: Device, options: "Options") -> None:
+    device.force_stop()
+    device.clear_logcat()
+    device.launch()
+    before = device.wait_for_process()
+    try:
+        device.shell("settings put system accelerometer_rotation 0")
+        for rotation in ("1", "0"):
+            device.shell(f"settings put system user_rotation {rotation}")
+            time.sleep(1.5)
+        after = device.pid()
+        if after != before:
+            raise CaseError(f"the process was recreated by a rotation ({before} -> {after})")
+        assert_no_crash(device)
+    finally:
+        device.shell("settings put system user_rotation 0", check=False)
+        device.shell("settings put system accelerometer_rotation 1", check=False)
+
+
+@case("tablet-layout", "a tablet-sized window lays out and survives a resize")
+def _tablet_layout(device: Device, options: "Options") -> None:
+    original_size = device.shell("wm size").strip()
+    original_density = device.shell("wm density").strip()
+    try:
+        device.force_stop()
+        device.clear_logcat()
+        device.shell("wm size 1600x2560")
+        device.shell("wm density 240")
+        device.launch()
+        device.wait_for_process()
+        time.sleep(2.5)
+        assert_no_crash(device)
+    finally:
+        device.shell("wm size reset", check=False)
+        device.shell("wm density reset", check=False)
+    _ = (original_size, original_density)
+
+
+@case(
+    "process-recreation",
+    "state survives the process being killed under the app",
+)
+def _process_recreation(device: Device, options: "Options") -> None:
+    # Was an xfail against B35, promoted when B35 landed: the navigation
+    # destination and the open player are `rememberSaveable` keys now, so there
+    # is saved instance state to come back to.
+    device.force_stop()
+    device.launch()
+    device.wait_for_process()
+    time.sleep(2.0)
+    device.shell(f"am broadcast -a android.intent.action.MAIN -p {PACKAGE}", check=False)
+    saved = device.shell(
+        f"dumpsys activity {PACKAGE} | grep -c 'mSavedInstanceState'", check=False
+    ).strip()
+    device.clear_logcat()
+    device.shell(f"am kill {PACKAGE}")
+    time.sleep(1.0)
+    device.launch()
+    device.wait_for_process()
+    time.sleep(2.0)
+    assert_no_crash(device)
+    if saved in ("", "0"):
+        raise CaseError(
+            "no saved instance state was recorded, so nothing can be restored "
+            "after a process kill (B35)"
+        )
+
+
+@case("offline-launch", "the app starts and stays up with no network")
+def _offline_launch(device: Device, options: "Options") -> None:
+    device.force_stop()
+    device.shell("cmd connectivity airplane-mode enable", check=False)
+    time.sleep(2.0)
+    try:
+        device.clear_logcat()
+        device.launch()
+        device.wait_for_process()
+        time.sleep(3.0)
+        assert_no_crash(device)
+    finally:
+        device.shell("cmd connectivity airplane-mode disable", check=False)
+        time.sleep(2.0)
+
+
+def jdk17_home() -> str | None:
+    candidates = [os.environ.get("JAVA_HOME", "")]
+    candidates += [
+        "/usr/lib/jvm/java-17-openjdk",
+        "/usr/lib/jvm/java-17-openjdk-amd64",
+        "/usr/lib/jvm/temurin-17-jdk",
+        "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home",
+    ]
+    for home in candidates:
+        java = Path(home) / "bin/java" if home else None
+        if java is None or not java.is_file():
+            continue
+        try:
+            out = subprocess.run(
+                [str(java), "-version"], capture_output=True, text=True, timeout=30
+            )
+        except (OSError, subprocess.SubprocessError):
+            continue
+        first = (out.stderr + out.stdout).splitlines()[:1]
+        if first and re.search(r'version "17[.\"]', first[0]):
+            return home
+    return None
+
+
+def android_sdk_home() -> str | None:
+    adb = shutil.which("adb")
+    if adb:
+        # <sdk>/platform-tools/adb
+        sdk = Path(adb).resolve().parent.parent
+        if (sdk / "platform-tools").is_dir():
+            return str(sdk)
+    for candidate in ("/opt/android-sdk", str(Path.home() / "Android/Sdk")):
+        if Path(candidate, "platform-tools").is_dir():
+            return candidate
+    return None
+
+
+def redact(text: str, share: "dict[str, str] | None") -> str:
+    for value in (share or {}).values():
+        if value:
+            text = text.replace(value, "<redacted>")
+    return text
+
+
+def run_instrumentation(
+    options: "Options",
+    only: str | None = None,
+    exclude: str | None = None,
+    share: "dict[str, str] | None" = None,
+) -> None:
+    gradlew = REPO_ROOT / "android/gradlew"
+    gradle = [str(gradlew)] if gradlew.is_file() and os.access(gradlew, os.X_OK) else None
+    if gradle is None:
+        if not shutil.which("gradle"):
+            raise CaseSkipped("no android/gradlew and no gradle on PATH")
+        gradle = ["gradle"]
+    task = "connectedReleaseAndroidTest" if options.test_release else "connectedDebugAndroidTest"
+    env = dict(os.environ)
+    # `testBuildType` is read from this variable in build.gradle.kts, so without
+    # it Gradle configures the debug variant and the release task simply does
+    # not exist.
+    env["ANDROID_TEST_BUILD_TYPE"] = "release" if options.test_release else "debug"
+    # Same reason build-android.sh looks for it: on a newer JVM the Kotlin
+    # compiler throws `IllegalArgumentException: 26.0.2` out of an IntelliJ
+    # version parser, which reads as a broken build rather than a wrong JDK.
+    java_home = jdk17_home()
+    if java_home is None:
+        raise CaseSkipped("no JDK 17 found; set JAVA_HOME (see docs/ANDROID.md)")
+    env["JAVA_HOME"] = java_home
+    # There is no android/local.properties in the repo, so Gradle finds the SDK
+    # only through the environment. adb is on PATH here by definition, and it
+    # lives in the SDK, so its location is the most reliable hint we have.
+    if not env.get("ANDROID_HOME") and not env.get("ANDROID_SDK_ROOT"):
+        sdk = android_sdk_home()
+        if sdk is None:
+            raise CaseSkipped("no Android SDK found; set ANDROID_HOME (see docs/ANDROID.md)")
+        env["ANDROID_HOME"] = sdk
+        env["ANDROID_SDK_ROOT"] = sdk
+    arguments = list(gradle) + ["--no-daemon", task]
+    if only:
+        arguments.append(f"-Pandroid.testInstrumentationRunnerArguments.class={only}")
+    if exclude:
+        arguments.append(f"-Pandroid.testInstrumentationRunnerArguments.notClass={exclude}")
+    for name, value in (share or {}).items():
+        # Passed as a Gradle property rather than written anywhere: a share link
+        # and its password are credentials, and this keeps them out of the repo,
+        # the reports and the build directory. They are still visible in this
+        # machine's process list for the duration of the run.
+        arguments.append(f"-Pandroid.testInstrumentationRunnerArguments.{name}={value}")
+    proc = subprocess.run(
+        arguments,
+        cwd=REPO_ROOT / "android",
+        capture_output=True,
+        text=True,
+        timeout=max(options.timeout, 1800),
+        env=env,
+    )
+    if proc.returncode != 0:
+        tail = "\n".join(redact((proc.stdout + proc.stderr), share).splitlines()[-40:])
+        raise CaseError(f"{task} failed:\n{tail}")
+    if only and "Starting 0 tests" in proc.stdout:
+        raise CaseError(f"no test matched {only}")
+
+
+@case("instrumentation", "the on-device test suite passes")
+def _instrumentation(device: Device, options: "Options") -> None:
+    # The live class is excluded here and run by the cases below, so a missing
+    # share cannot make this case look like it covered them.
+    run_instrumentation(options, exclude=LIVE_TEST_CLASS)
+
+
+def live_arguments(options: "Options") -> dict[str, str]:
+    share = {"pstr.shareUrl": options.share_url or ""}
+    if options.share_password:
+        share["pstr.sharePassword"] = options.share_password
+    return share
+
+
+
+def _pending(reason: str):
+    def run(device: Device, options: "Options") -> None:
+        raise CasePending(reason)
+
+    return run
+
+
+# One run of the live class serves every live case. Running them separately
+# would be cleaner in principle, but each run re-adds the share and re-crawls it
+# from an empty catalog — six minutes apiece against a real share — and the
+# crawl is not what any of these cases is testing.
+LIVE_RUN: "dict[str, tuple[str, str]] | None" = None
+
+
+def live_results(options: "Options") -> "dict[str, tuple[str, str]]":
+    global LIVE_RUN
+    if LIVE_RUN is not None:
+        return LIVE_RUN
+    results_dir = REPO_ROOT / "android/app/build/outputs/androidTest-results/connected" / (
+        "release" if options.test_release else "debug"
+    )
+    for stale in results_dir.glob("*.xml"):
+        stale.unlink()
+    failure: CaseError | None = None
+    try:
+        run_instrumentation(options, only=LIVE_TEST_CLASS, share=live_arguments(options))
+    except CaseError as error:
+        # Individual methods are reported per case below; this only matters if
+        # nothing ran at all.
+        failure = error
+    parsed: dict[str, tuple[str, str]] = {}
+    for report in results_dir.glob("*.xml"):
+        for testcase in ET.parse(report).getroot().iter("testcase"):
+            name = testcase.get("name") or ""
+            problem = next(iter(testcase.iter("failure")), None)
+            if problem is not None:
+                parsed[name] = ("failed", (problem.text or "").strip())
+            elif next(iter(testcase.iter("skipped")), None) is not None:
+                parsed[name] = ("skipped", "the test skipped itself by assumption")
+            else:
+                parsed[name] = ("passed", "")
+    if not parsed:
+        raise failure or CaseError("the live suite produced no results")
+    LIVE_RUN = parsed
+    return parsed
+
+
+def _live(method: str):
+    """Reads one method out of the shared live run; the share is never stored."""
+
+    def run(device: Device, options: "Options") -> None:
+        results = live_results(options)
+        status, detail = results.get(method, ("missing", ""))
+        if status == "failed":
+            raise CaseError(detail or f"{method} failed")
+        if status == "skipped":
+            raise CaseSkipped(detail)
+        if status == "missing":
+            raise CaseError(f"{method} did not run; the live class may have been renamed")
+
+    return run
+
+
+for _name, _what, _method in (
+    (
+        "playback",
+        "an episode decodes through libmpv from the encrypted stream",
+        "libmpvDecodesTheDecryptedStream",
+    ),
+    (
+        "catalog",
+        "the share link resolves into a catalog of playable files",
+        "theShareResolvesIntoAPlayableCatalog",
+    ),
+    (
+        "stream-open",
+        "an episode opens as a sized, seekable revision",
+        "openingAnEpisodeYieldsASeekableRevision",
+    ),
+    (
+        "download-cancel-resume",
+        "a cancelled download leaves a resumable .part and resumes from it",
+        "aCancelledDownloadLeavesAResumablePartFile",
+    ),
+    (
+        "watch-state",
+        "a resume position survives reopening the catalog",
+        "aResumePositionSurvivesReopeningTheCatalog",
+    ),
+):
+    REGISTRY.append(Case(name=_name, what=_what, run=_live(_method), needs_share=True))
+
+# Still unimplemented, and the only case left that is. No longer blocked on the
+# app: B40 landed, so there is correct behaviour to assert. What is missing is a
+# driver — every live case here reads the engine and libmpv directly, and this
+# one needs the activity with the player composed on screen before PiP means
+# anything.
+REGISTRY.append(
+    Case(
+        name="picture-in-picture",
+        what="entering PiP keeps playing and shows only video",
+        run=_pending(
+            "needs an activity-level driver: the live suite exercises the engine "
+            "and libmpv, not the composition, and PiP is a property of the window"
+        ),
+        needs_share=True,
+    )
+)
+
+
+# --------------------------------------------------------------------------
+# runner
+
+
+@dataclass
+class Options:
+    timeout: int = 120
+    fail_fast: bool = False
+    test_release: bool = False
+    share_url: str | None = None
+    share_password: str | None = None
+
+
+@dataclass
+class Result:
+    name: str
+    status: str  # passed | failed | skipped | xfailed | xpassed | pending
+    detail: str = ""
+    seconds: float = 0.0
+
+
+@dataclass
+class Run:
+    results: list[Result] = field(default_factory=list)
+
+    def count(self, status: str) -> int:
+        return sum(1 for result in self.results if result.status == status)
+
+
+def select(names: list[Case], only: str | None) -> list[Case]:
+    if not only:
+        return names
+    wanted = [part.strip() for part in only.split(",") if part.strip()]
+    return [case for case in names if any(part in case.name for part in wanted)]
+
+
+def run_cases(device: Device, cases: list[Case], options: Options) -> Run:
+    run = Run()
+    for entry in cases:
+        started = time.time()
+        status, detail = "passed", ""
+        try:
+            # The share check comes second on purpose: an unimplemented case is
+            # pending whether or not a share is configured, and reporting it as
+            # "skipped" would let a missing environment variable disguise a hole
+            # in the matrix.
+            entry.run(device, options)
+            if entry.needs_share and not options.share_url:
+                raise CaseSkipped("PSTR_ACCEPTANCE_SHARE_URL is not set")
+            if entry.xfail:
+                status = "xpassed"
+                detail = f"{entry.xfail} looks fixed — promote this case and close it"
+        except CasePending as pending:
+            status, detail = "pending", str(pending)
+        except CaseSkipped as skipped:
+            status, detail = "skipped", str(skipped)
+        except (CaseError, subprocess.TimeoutExpired) as failure:
+            if entry.xfail:
+                status, detail = "xfailed", f"{entry.xfail}: {failure}"
+            else:
+                status, detail = "failed", str(failure)
+        seconds = time.time() - started
+        run.results.append(Result(entry.name, status, detail, seconds))
+        mark = {
+            "passed": "ok",
+            "failed": "FAIL",
+            "skipped": "skip",
+            "xfailed": "xfail",
+            "xpassed": "XPASS",
+            "pending": "pending",
+        }[status]
+        print(f"[{mark:>7}] {entry.name} ({seconds:.1f}s)")
+        if detail:
+            for line in detail.splitlines():
+                print(f"          {line}")
+        if options.fail_fast and status in ("failed", "xpassed"):
+            break
+    return run
+
+
+def write_json(run: Run, path: Path) -> None:
+    path.write_text(
+        json.dumps(
+            {
+                "results": [
+                    {
+                        "name": result.name,
+                        "status": result.status,
+                        "detail": result.detail,
+                        "seconds": round(result.seconds, 3),
+                    }
+                    for result in run.results
+                ]
+            },
+            indent=2,
+        )
+    )
+
+
+def write_junit(run: Run, path: Path) -> None:
+    suite = ET.Element(
+        "testsuite",
+        name="android-acceptance",
+        tests=str(len(run.results)),
+        failures=str(run.count("failed") + run.count("xpassed")),
+        skipped=str(run.count("skipped") + run.count("pending")),
+    )
+    for result in run.results:
+        node = ET.SubElement(
+            suite, "testcase", name=result.name, time=f"{result.seconds:.3f}"
+        )
+        if result.status in ("failed", "xpassed"):
+            ET.SubElement(node, "failure", message=result.detail or result.status)
+        elif result.status in ("skipped", "pending", "xfailed"):
+            ET.SubElement(node, "skipped", message=result.detail or result.status)
+    ET.ElementTree(suite).write(path, encoding="utf-8", xml_declaration=True)
+
+
+def attached_serials() -> list[str]:
+    out = subprocess.run(["adb", "devices"], capture_output=True, text=True).stdout
+    return [
+        line.split()[0]
+        for line in out.splitlines()[1:]
+        if line.strip() and line.split()[-1] == "device"
+    ]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--serial")
+    parser.add_argument("--apk")
+    parser.add_argument(
+        "--package",
+        help="installed applicationId; inferred from the APK's build type when omitted",
+    )
+    parser.add_argument(
+        "--release",
+        action="store_true",
+        help="test the minified release APK — the build that actually ships",
+    )
+    parser.add_argument("--no-install", action="store_true")
+    parser.add_argument("--list", action="store_true")
+    parser.add_argument("--fail-fast", action="store_true")
+    parser.add_argument("--timeout", type=int, default=120)
+    parser.add_argument("--report-json")
+    parser.add_argument("--report-junit")
+    parser.add_argument("--keep-going-on-crash", action="store_true")
+    args = parser.parse_args()
+
+    release = args.release or os.environ.get("ANDROID_TEST_BUILD_TYPE") == "release"
+    apk = Path(args.apk) if args.apk else (RELEASE_APK if release else DEBUG_APK)
+    global PACKAGE
+    if args.package:
+        PACKAGE = args.package
+    elif "debug" in apk.name or "debug" in apk.parent.name:
+        PACKAGE = f"{APPLICATION_ID}.debug"
+    else:
+        PACKAGE = APPLICATION_ID
+
+    cases = select(REGISTRY, os.environ.get("PSTR_ACCEPTANCE_ONLY"))
+    if args.list:
+        width = max(len(entry.name) for entry in cases) if cases else 0
+        for entry in cases:
+            tags = []
+            if entry.xfail:
+                tags.append(f"xfail:{entry.xfail}")
+            if entry.needs_share:
+                tags.append("live")
+            suffix = f"  [{', '.join(tags)}]" if tags else ""
+            print(f"{entry.name:<{width}}  {entry.what}{suffix}")
+        return 0
+    if not cases:
+        print("no case matched PSTR_ACCEPTANCE_ONLY", file=sys.stderr)
+        return 2
+
+    serials = attached_serials()
+    serial = args.serial
+    if serial is None:
+        if len(serials) != 1:
+            print(
+                f"expected exactly one attached device, found {len(serials)}"
+                + (f": {', '.join(serials)}" if serials else ""),
+                file=sys.stderr,
+            )
+            return 2
+        serial = serials[0]
+
+    device = Device(serial, args.timeout)
+    if device.api_level < 31:
+        print(
+            f"the app targets Android 12 (API 31) and newer; this device is API {device.api_level}",
+            file=sys.stderr,
+        )
+        return 2
+
+    if not args.no_install:
+        if not apk.is_file():
+            build = "release" if release else "debug"
+            print(
+                f"no APK at {apk}; run `bash scripts/build-android.sh {build}` first",
+                file=sys.stderr,
+            )
+            return 2
+        print(f"installing {apk.name} as {PACKAGE} on {serial} ({device.abi}, API {device.api_level})")
+        device.run("install", "-r", "-g", str(apk), timeout=600)
+
+    options = Options(
+        timeout=args.timeout,
+        fail_fast=args.fail_fast,
+        test_release=release,
+        share_url=os.environ.get("PSTR_ACCEPTANCE_SHARE_URL"),
+        share_password=os.environ.get("PSTR_ACCEPTANCE_SHARE_PASSWORD"),
+    )
+    run = run_cases(device, cases, options)
+
+    if args.report_json:
+        write_json(run, Path(args.report_json))
+    if args.report_junit:
+        write_junit(run, Path(args.report_junit))
+
+    print()
+    print(
+        "  ".join(
+            f"{status}={run.count(status)}"
+            for status in ("passed", "failed", "xfailed", "xpassed", "skipped", "pending")
+        )
+    )
+    if run.count("pending"):
+        print(
+            f"the matrix docs/ANDROID.md requires is incomplete: "
+            f"{run.count('pending')} case(s) are specified but not implemented"
+        )
+    if run.count("xpassed"):
+        print("a case marked xfail passed — the bug it tracks is fixed; promote the case")
+
+    return 1 if run.count("failed") or run.count("xpassed") else 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:
+        sys.exit(130)

scripts/android-acceptance.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# On-device acceptance for the Android client. Drives a real device or emulator
+# through the matrix docs/ANDROID.md requires before Android work is submitted.
+set -Eeuo pipefail
+
+usage() {
+    cat >&2 <<'EOF'
+usage: scripts/android-acceptance.sh [OPTION ...]
+
+Runs against one attached device or emulator. The app is installed from the
+debug APK unless --no-install is given; nothing here needs a Proton account
+except the cases marked "live", which skip cleanly without one.
+
+Options:
+  --serial SERIAL     target this device (default: the only attached one)
+  --apk PATH          install this APK instead of the debug output
+  --no-install        use whatever build is already installed
+  --list              print every case and what it needs, then exit
+  --fail-fast         stop at the first failure instead of continuing
+  --timeout SECONDS   per-case limit (default 120)
+  --report-json PATH  machine-readable results
+  --report-junit PATH JUnit XML for CI
+  --keep-going-on-crash
+                      report a crash as a failure and continue rather than
+                      aborting the run
+
+Environment:
+  PSTR_ACCEPTANCE_ONLY=name[,name]   run only these cases (substring match)
+  PSTR_ACCEPTANCE_SHARE_URL          public link for the live cases
+  PSTR_ACCEPTANCE_SHARE_PASSWORD     custom password, if the link needs one
+
+Live cases are destructive to the app's own state: they clear app data between
+phases. They never write to the share.
+EOF
+    exit 2
+}
+
+case "${1:-}" in
+    -h|--help) usage ;;
+esac
+
+command -v python3 >/dev/null || { echo "python3 is required" >&2; exit 2; }
+command -v adb >/dev/null || { echo "adb is required (Android platform-tools)" >&2; exit 2; }
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+exec python3 -u "$script_dir/android-acceptance.py" "$@"

scripts/build-android.sh

@@ -7,11 +7,14 @@ android_dir="$repo_root/android"
 
 usage() {
   echo "usage: $0 {debug|check|release|signed|all}"
+  echo
+  echo "  check  ktlint, Android lint and host unit tests — no device needed."
+  echo "         On-device coverage is scripts/android-acceptance.sh."
 }
 
 case "${1:-}" in
   debug) tasks=(assembleDebug) ;;
-  check) tasks=(lintDebug testDebugUnitTest) ;;
+  check) tasks=(ktlintCheck lintDebug testDebugUnitTest) ;;
   release) tasks=(assembleRelease bundleRelease) ;;
   signed)
     required=(
@@ -28,10 +31,42 @@ case "${1:-}" in
     done
     tasks=(assembleRelease bundleRelease)
     ;;
-  all) tasks=(lintDebug testDebugUnitTest assembleDebug assembleRelease bundleRelease) ;;
+  all) tasks=(ktlintCheck lintDebug testDebugUnitTest assembleDebug assembleRelease bundleRelease) ;;
   *) usage >&2; exit 2 ;;
 esac
 
+# The Android toolchain needs JDK 17. A newer JVM does not fail with a version
+# message — the Kotlin compiler throws `IllegalArgumentException: 26.0.2` out of
+# an IntelliJ version parser, which reads as a broken build rather than a wrong
+# JDK. Find 17 before that can happen.
+java_major() {
+  local java_bin="$1"
+  [[ -x "$java_bin" ]] || return 1
+  "$java_bin" -version 2>&1 | sed -n '1s/.*version "\([0-9]*\).*/\1/p'
+}
+
+if [[ "$(java_major "${JAVA_HOME:-}/bin/java" || true)" != "17" ]]; then
+  found=""
+  for candidate in \
+    /usr/lib/jvm/java-17-openjdk \
+    /usr/lib/jvm/java-17-openjdk-amd64 \
+    /usr/lib/jvm/temurin-17-jdk \
+    /Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home; do
+    if [[ "$(java_major "$candidate/bin/java" || true)" == "17" ]]; then
+      found="$candidate"
+      break
+    fi
+  done
+  if [[ -z "$found" ]] && [[ "$(java_major "$(command -v java || echo /nonexistent)" || true)" == "17" ]]; then
+    found="$(dirname "$(dirname "$(readlink -f "$(command -v java)")")")"
+  fi
+  if [[ -z "$found" ]]; then
+    echo "error: JDK 17 is required (see docs/ANDROID.md); set JAVA_HOME to it" >&2
+    exit 1
+  fi
+  export JAVA_HOME="$found"
+fi
+
 if [[ -x "$android_dir/gradlew" ]]; then
   gradle=("$android_dir/gradlew")
 elif command -v gradle >/dev/null 2>&1; then

scripts/build-libmpv-android.sh

@@ -171,6 +171,10 @@ stage_shared_dependency_closure() {
 
 mkdir -p "$destination/include/mpv"
 cp "$source_dir/buildscripts/prefix/arm64/include/mpv/"*.h "$destination/include/mpv/"
+# FFmpeg's JNI entry points are not part of the mpv API, but registering the
+# JavaVM MediaCodec needs is our job now that mpv-android's JNI layer is gone.
+mkdir -p "$destination/include/libavcodec"
+cp "$source_dir/buildscripts/prefix/arm64/include/libavcodec/jni.h" "$destination/include/libavcodec/"
 stage_shared_dependency_closure arm64 arm64-v8a aarch64-linux-android
 stage_shared_dependency_closure x86_64 x86_64 x86_64-linux-android