[BW-DL-01] Audit actionable download and offline recovery UX #15

Closed
opened 2026-09-18 08:45:40 +02:00 by alexander · 2 comments
Owner

Migrated from GitHub issue #104. Forgejo issue: #15. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

Classification

Active planning/audit item. No download behavior change in this issue.

Problem / opportunity

BookWave already has substantial download/offline architecture, but the user experience around failure, pause, storage exhaustion/removal, network constraints, stale manifests, and repair/retry paths has accumulated incrementally. Before adding a download/status widget or more automation, we need to identify which states are genuinely actionable for a listener and whether the current UI gives the right explanation and recovery action.

User value

Make offline listening more trustworthy: when a download is not usable, BookWave should say what happened, what still exists locally, and the safest next action instead of reducing every problem to a generic failure/retry state.

Scope

Audit current download architecture, UI, state model, risks, device-test evidence, PRODUCT_SPEC/ADRs, and reference-client research. Produce a concrete recovery UX plan covering at least:

  • failed downloads;
  • intentionally paused downloads;
  • waiting for Wi-Fi / cellular-policy constraints;
  • insufficient storage;
  • selected/removable volume unavailable;
  • partial .part data and resumability;
  • checksum/verification failure;
  • manifest/file disagreement;
  • profile authorization versus physical file ownership;
  • server unreachable / authentication expired while downloading;
  • app/process death and WorkManager retry state;
  • completed local file that becomes unreadable or disappears;
  • what should be repairable automatically versus require explicit user action.

For each state, record:

  • user-facing wording/state;
  • primary action;
  • secondary action if any;
  • whether the action is safe offline;
  • whether existing partial data is preserved;
  • whether another profile may still be authorized to use the same physical copy;
  • whether a notification/system surface is justified;
  • whether the state is useful enough to support a future widget.

End with small independent implementation slices rather than one broad 'downloads redesign' PR.

Explicitly out of scope

  • No download implementation changes in this issue.
  • No widget implementation.
  • No SAF/user-chosen-directory work unless an observed recovery state directly depends on it.
  • No rewrite of the existing download coordinator or WorkManager architecture without evidence that current seams cannot support the required UX.
  • No automatic deletion or destructive repair without explicit product rules.

Dependencies

None for the audit. Any later implementation slices may depend on current download architecture or documentation decisions discovered here.

Architecture seams affected

Planning must inspect and preserve the distinction between:

  • physical downloaded file ownership on the device;
  • per-profile authorization/access;
  • download manifest state;
  • WorkManager/coordinator execution state;
  • network policy;
  • storage-volume selection;
  • library/local-availability projections;
  • UI recovery actions.

Server / API assumptions

Audiobookshelf remains the source for authorization/library identity and download media URLs. The audit must not assume the server can repair missing local files or expose state it does not actually provide. Authentication expiry and server-unreachable states should reuse existing application error semantics where possible.

Storage / migration implications

Audit only. Any proposed future state additions must say whether they require manifest/schema migration and how existing partial/completed downloads are interpreted safely. Existing files must never be deleted merely because a newer UI cannot classify them.

Privacy / security

Do not expose book titles/server information in diagnostics or system surfaces beyond existing privacy policy. Recovery actions must respect active-profile authorization; a physical file existing on disk does not by itself grant another profile access.

Automated-test level

The audit should map every recommended implementation slice to its appropriate level: pure state-machine/domain tests, manifest/storage tests, WorkManager tests, repository tests, and UI/Robolectric tests. Destructive or filesystem repair behavior requires explicit regression coverage.

Device / platform acceptance

Plan device tests for removable storage loss/return where possible, airplane/offline mode, Wi-Fi/cellular policy, process death during transfer, low-storage behavior, and playback of a completed download after server loss. Do not label emulator/JVM evidence as equivalent to actual removable-storage behavior.

Estimated effort

Audit/planning: Medium. Follow-up implementation cost to be estimated per slice.

Implementation risk

Audit: Low. Future recovery work: Medium/high because incorrect repair/deletion semantics can destroy useful partial data or make valid offline media unavailable.

Start now in parallel with BW-DOC-01. Finish the audit before deciding whether a download/status widget deserves roadmap priority.

Acceptance criteria

  • Current download/offline states and their owners are documented from main, not inferred from old plans.
  • Every important failure/pause/network/storage state has a recommended user-visible meaning and safe recovery action.
  • Automatic versus explicit recovery boundaries are stated.
  • Profile authorization and one-copy physical-file semantics are preserved.
  • The audit identifies which current UX is already correct, which is misleading, and which states are missing entirely.
  • Follow-up implementation work is split into independently executable issues with dependencies, tests, and device acceptance.
  • A future download widget is recommended only if there is actionable persistent state worth occupying Home-screen space.
> Migrated from [GitHub issue #104](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/104). Forgejo issue: #15. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Classification Active planning/audit item. No download behavior change in this issue. ## Problem / opportunity BookWave already has substantial download/offline architecture, but the user experience around failure, pause, storage exhaustion/removal, network constraints, stale manifests, and repair/retry paths has accumulated incrementally. Before adding a download/status widget or more automation, we need to identify which states are genuinely actionable for a listener and whether the current UI gives the right explanation and recovery action. ## User value Make offline listening more trustworthy: when a download is not usable, BookWave should say what happened, what still exists locally, and the safest next action instead of reducing every problem to a generic failure/retry state. ## Scope Audit current download architecture, UI, state model, risks, device-test evidence, PRODUCT_SPEC/ADRs, and reference-client research. Produce a concrete recovery UX plan covering at least: - failed downloads; - intentionally paused downloads; - waiting for Wi-Fi / cellular-policy constraints; - insufficient storage; - selected/removable volume unavailable; - partial `.part` data and resumability; - checksum/verification failure; - manifest/file disagreement; - profile authorization versus physical file ownership; - server unreachable / authentication expired while downloading; - app/process death and WorkManager retry state; - completed local file that becomes unreadable or disappears; - what should be repairable automatically versus require explicit user action. For each state, record: - user-facing wording/state; - primary action; - secondary action if any; - whether the action is safe offline; - whether existing partial data is preserved; - whether another profile may still be authorized to use the same physical copy; - whether a notification/system surface is justified; - whether the state is useful enough to support a future widget. End with small independent implementation slices rather than one broad 'downloads redesign' PR. ## Explicitly out of scope - No download implementation changes in this issue. - No widget implementation. - No SAF/user-chosen-directory work unless an observed recovery state directly depends on it. - No rewrite of the existing download coordinator or WorkManager architecture without evidence that current seams cannot support the required UX. - No automatic deletion or destructive repair without explicit product rules. ## Dependencies None for the audit. Any later implementation slices may depend on current download architecture or documentation decisions discovered here. ## Architecture seams affected Planning must inspect and preserve the distinction between: - physical downloaded file ownership on the device; - per-profile authorization/access; - download manifest state; - WorkManager/coordinator execution state; - network policy; - storage-volume selection; - library/local-availability projections; - UI recovery actions. ## Server / API assumptions Audiobookshelf remains the source for authorization/library identity and download media URLs. The audit must not assume the server can repair missing local files or expose state it does not actually provide. Authentication expiry and server-unreachable states should reuse existing application error semantics where possible. ## Storage / migration implications Audit only. Any proposed future state additions must say whether they require manifest/schema migration and how existing partial/completed downloads are interpreted safely. Existing files must never be deleted merely because a newer UI cannot classify them. ## Privacy / security Do not expose book titles/server information in diagnostics or system surfaces beyond existing privacy policy. Recovery actions must respect active-profile authorization; a physical file existing on disk does not by itself grant another profile access. ## Automated-test level The audit should map every recommended implementation slice to its appropriate level: pure state-machine/domain tests, manifest/storage tests, WorkManager tests, repository tests, and UI/Robolectric tests. Destructive or filesystem repair behavior requires explicit regression coverage. ## Device / platform acceptance Plan device tests for removable storage loss/return where possible, airplane/offline mode, Wi-Fi/cellular policy, process death during transfer, low-storage behavior, and playback of a completed download after server loss. Do not label emulator/JVM evidence as equivalent to actual removable-storage behavior. ## Estimated effort Audit/planning: Medium. Follow-up implementation cost to be estimated per slice. ## Implementation risk Audit: Low. Future recovery work: Medium/high because incorrect repair/deletion semantics can destroy useful partial data or make valid offline media unavailable. ## Recommended sequence Start now in parallel with BW-DOC-01. Finish the audit before deciding whether a download/status widget deserves roadmap priority. ## Acceptance criteria - Current download/offline states and their owners are documented from `main`, not inferred from old plans. - Every important failure/pause/network/storage state has a recommended user-visible meaning and safe recovery action. - Automatic versus explicit recovery boundaries are stated. - Profile authorization and one-copy physical-file semantics are preserved. - The audit identifies which current UX is already correct, which is misleading, and which states are missing entirely. - Follow-up implementation work is split into independently executable issues with dependencies, tests, and device acceptance. - A future download widget is recommended only if there is actionable persistent state worth occupying Home-screen space.
Author
Owner

Imported GitHub comment by @AlexanderWilhelmsenBerg, originally posted 2026-09-07T11:30:15Z. Original comment

Superseded by the full BW-DL-01 audit summary in #104. The audit remains issue-based; implementation is split into #107–#112. GitHub PR #106 is planning-only material and is being closed without merge.

> Imported GitHub comment by **@AlexanderWilhelmsenBerg**, originally posted 2026-09-07T11:30:15Z. [Original comment](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/104#issuecomment-5569964615) Superseded by the full BW-DL-01 audit summary in #104. The audit remains issue-based; implementation is split into #107–#112. [GitHub PR #106](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/106) is planning-only material and is being closed without merge.
Author
Owner

Imported GitHub comment by @AlexanderWilhelmsenBerg, originally posted 2026-09-07T11:41:08Z. Original comment

BW-DL-01 audit result

This issue is the planning/audit owner. It does not represent an implementation PR.

Current-state findings from main

  1. Failure reason is stored but lost before UI — DownloadedBookEntity.failureSummary is populated by DefaultDownloadRepository.markFailed(...), but DownloadMappers.toDomain(...) does not carry it into OfflineBook. The Downloads UI therefore knows that a row failed but cannot explain the safe failure reason already persisted.
  2. Failed rows can expose the wrong action — every incomplete non-paused row currently renders Pause. A Failed row can therefore call PauseDownloadUseCase, become Paused, and clear the failure reason instead of offering Retry.
  3. Durable manifest state and WorkManager execution state are conflated in presentation — retryable failures are persisted as Failed before BookDownloadWorker returns Result.retry(). During WorkManager retry/backoff, the screen can say Failed even though BookWave will continue automatically. Network constraints can similarly leave work waiting while the manifest only says incomplete/queued.
  4. Removable-storage absence is currently indistinguishable from missing/corrupt media during verification — an intact completed copy on a removed SD/removable volume can be marked Failed because its file:// path is temporarily unavailable. Reinserting the card does not automatically restore the manifest to Complete. The selected missing volume also falls back to internal storage for new downloads without making that fallback especially clear to the listener.
  5. Device-wide management semantics are not fully aligned with profile-scoped claims — the Downloads settings screen intentionally lists every physical copy on the device, including title-hidden rows, but Remove resolves the active profile and releases only that profile's claim. Pin state is aggregated across claims while the toggle writes only the active profile's claim. The product needs an explicit distinction between profile-level removal and device-copy removal before changing destructive behavior.
  6. Partial-data preservation is already good and should remain the default — failures and pauses keep .part data; Retry/Resume can reuse it. OfflineFiles.discardPartials(...) already exists and is a good candidate for an explicit secondary destructive recovery action rather than automatic cleanup.
  7. Several important ownership boundaries are already correct — one physical copy can serve several profile claims; progress remains per profile; worker input captures the authorizing profile rather than reading the currently active profile later; verification does not automatically delete broken files; WorkManager owns transient retry/constraint execution state and Room owns the durable manifest.

Implementation slices created

  • #107 BW-DL-02 — expose safe failure reason and define recovery presentation state. No schema migration expected for the reason because failureSummary already exists.
  • #108 BW-DL-03 — correct Pause / Resume / Retry actions. Depends on #107.
  • #109 BW-DL-04 — project WorkManager waiting/retry evidence into Downloads UX without mirroring WorkInfo into Room. Depends on #107; recommended after #108.
  • #110 BW-DL-05 — treat unavailable removable storage separately from corrupt/missing files; real removable-storage device testing required. Recommended after #107.
  • #111 BW-DL-06 — make profile-claim removal versus device-copy removal/pinning semantics explicit. Blocked on product decision; do not implement yet.
  • #112 BW-DL-07 — expose explicit confirmed Discard partial download as a secondary action. Depends on #108.

#107 -> #108 -> #109, then #110; #112 may proceed after #108 independently. #111 waits for the owner decision and should not block the non-destructive recovery work.

Widget conclusion

Do not prioritize a generic download-count widget. Once #107–#110 exist, reconsider a download/status widget only if it can surface persistent actionable states such as Waiting for Wi-Fi, Retry needed, or Storage unavailable. A raw count is not worth Home-screen space.

Audit status

The planning work of BW-DL-01 is complete enough to hand off its child issues. Application behavior remains unchanged by this issue.

> Imported GitHub comment by **@AlexanderWilhelmsenBerg**, originally posted 2026-09-07T11:41:08Z. [Original comment](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/104#issuecomment-5570086472) ## BW-DL-01 audit result This issue is the planning/audit owner. It does **not** represent an implementation PR. ### Current-state findings from `main` 1. **Failure reason is stored but lost before UI** — `DownloadedBookEntity.failureSummary` is populated by `DefaultDownloadRepository.markFailed(...)`, but `DownloadMappers.toDomain(...)` does not carry it into `OfflineBook`. The Downloads UI therefore knows that a row failed but cannot explain the safe failure reason already persisted. 2. **Failed rows can expose the wrong action** — every incomplete non-paused row currently renders Pause. A `Failed` row can therefore call `PauseDownloadUseCase`, become `Paused`, and clear the failure reason instead of offering Retry. 3. **Durable manifest state and WorkManager execution state are conflated in presentation** — retryable failures are persisted as `Failed` before `BookDownloadWorker` returns `Result.retry()`. During WorkManager retry/backoff, the screen can say Failed even though BookWave will continue automatically. Network constraints can similarly leave work waiting while the manifest only says incomplete/queued. 4. **Removable-storage absence is currently indistinguishable from missing/corrupt media during verification** — an intact completed copy on a removed SD/removable volume can be marked Failed because its `file://` path is temporarily unavailable. Reinserting the card does not automatically restore the manifest to Complete. The selected missing volume also falls back to internal storage for new downloads without making that fallback especially clear to the listener. 5. **Device-wide management semantics are not fully aligned with profile-scoped claims** — the Downloads settings screen intentionally lists every physical copy on the device, including title-hidden rows, but Remove resolves the active profile and releases only that profile's claim. Pin state is aggregated across claims while the toggle writes only the active profile's claim. The product needs an explicit distinction between profile-level removal and device-copy removal before changing destructive behavior. 6. **Partial-data preservation is already good and should remain the default** — failures and pauses keep `.part` data; Retry/Resume can reuse it. `OfflineFiles.discardPartials(...)` already exists and is a good candidate for an explicit secondary destructive recovery action rather than automatic cleanup. 7. **Several important ownership boundaries are already correct** — one physical copy can serve several profile claims; progress remains per profile; worker input captures the authorizing profile rather than reading the currently active profile later; verification does not automatically delete broken files; WorkManager owns transient retry/constraint execution state and Room owns the durable manifest. ### Implementation slices created - #107 **BW-DL-02** — expose safe failure reason and define recovery presentation state. No schema migration expected for the reason because `failureSummary` already exists. - #108 **BW-DL-03** — correct Pause / Resume / Retry actions. Depends on #107. - #109 **BW-DL-04** — project WorkManager waiting/retry evidence into Downloads UX without mirroring WorkInfo into Room. Depends on #107; recommended after #108. - #110 **BW-DL-05** — treat unavailable removable storage separately from corrupt/missing files; real removable-storage device testing required. Recommended after #107. - #111 **BW-DL-06** — make profile-claim removal versus device-copy removal/pinning semantics explicit. **Blocked on product decision; do not implement yet.** - #112 **BW-DL-07** — expose explicit confirmed `Discard partial download` as a secondary action. Depends on #108. ### Recommended implementation order `#107 -> #108 -> #109`, then `#110`; `#112` may proceed after #108 independently. #111 waits for the owner decision and should not block the non-destructive recovery work. ### Widget conclusion Do **not** prioritize a generic download-count widget. Once #107–#110 exist, reconsider a download/status widget only if it can surface persistent actionable states such as `Waiting for Wi-Fi`, `Retry needed`, or `Storage unavailable`. A raw count is not worth Home-screen space. ### Audit status The planning work of BW-DL-01 is complete enough to hand off its child issues. Application behavior remains unchanged by this issue.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#15
No description provided.