Redesign Android Auto browse home with artwork and profiles #65

Open
opened 2026-09-19 22:57:11 +02:00 by alexander · 4 comments
Owner

Goal

Replace the current Android Auto browse hierarchy with the settled four-destination home and add artwork/profile switching as a dedicated implementation slice.

This is a new issue and new PR. Do not fold this work into #35 / PR #61.

Definitive product decision

The Android Auto root is, in this order:

  1. Continue
  2. Series
  3. Authors
  4. Profiles

There is no general Library root in this design.

Series ordering

The Series destination is ordered by playback recency when BookWave has playback evidence:

  • series with playback activity are ordered by their most recent played/progress activity, newest first;
  • series without playback activity follow alphabetically;
  • ties use alphabetical order for determinism.

Books inside a series keep the existing canonical series-sequence ordering from LIB-003.

History / queue

  • History is not part of the Android Auto browse library.
  • Do not recreate History under another car browse destination.
  • The standard Android Auto Queue is not required. #35 owns suppressing it on the standard player surface.
  • Do not implement a synthetic History queue or synthetic player timeline.

Artwork and presentation

Android Auto browse rows should use artwork wherever BookWave has safe cached artwork:

  • book rows use the book cover;
  • series rows use a representative cached book cover;
  • author rows follow the existing LIB-002 artwork policy (confirmed portrait when available, cached representative cover as fallback);
  • missing/offline artwork degrades cleanly to the host placeholder.

Continue, Series, Authors and the book rows reached through Series/Authors request the host's artwork-first grid/card
content style. Profiles remains text-first/list-like so active, lock and account state stays legible.

The automotive host owns the exact background, card chrome, spacing and typography. BookWave supplies its shipped
teal platform accent where the host honours the app accent; this issue does not introduce a custom-drawn car
background.

Artwork supplied to Android Auto must be readable by the car/media host process, work from cached/offline state,
must not initiate a fresh artwork network fetch on behalf of the host, and must never expose credentials or tokens
in a URI.

Profiles

Profiles is a first-class Android Auto browse destination.

  • list the saved profiles using existing profile identity/display data and clearly mark the active profile;
  • selecting a different profile uses the existing AUTH-002 / PRODUCT_SPEC 6.5 atomic profile-switch behavior: flush progress, pause playback by default, change profile context atomically, invalidate the car browse tree, and restore the new profile's state paused;
  • switching from Android Auto must not bypass AUTH-005/profile locking. If a target profile requires an unlock that cannot be completed in the car surface, explain that the profile must be unlocked on the phone rather than exposing its library;
  • after a successful switch, no rows from the previous profile may remain visible through a subscribed/cached browse node.

Current state to replace

Current Android Auto root on main is:

  • Continue
  • Series
  • Authors
  • Library

The Library subtree currently contains Chapters, History, Downloads, Recently added, Listen again, Discover and Audio output. This issue deliberately replaces that information architecture rather than adding another tab to it.

Acceptance criteria

  • Root contains exactly Continue → Series → Authors → Profiles.
  • History is absent from the Android Auto browse tree.
  • The old Library root/subtree is no longer exposed through Android Auto.
  • Series order follows playback-recency-then-alphabetical semantics above.
  • Books inside each series retain canonical series sequence ordering.
  • Continue, Series and Authors request artwork-first grid/card presentation; Profiles remains list-like.
  • BookWave exposes its shipped teal platform accent without depending on a custom Android Auto background.
  • Continue/book rows render cached cover artwork on Android Auto when available.
  • Series rows render a representative cached cover.
  • Author artwork follows LIB-002 and remains safe/offline-capable.
  • Host artwork reads do not trigger a new network fetch.
  • Artwork URIs are host-readable and contain no reusable credential material.
  • Profiles lists saved profiles and marks the active one.
  • A successful profile switch flushes/preserves progress and pauses by default per PRODUCT_SPEC 6.5.
  • A locked profile cannot be entered from Android Auto without satisfying existing lock policy; no lock bypass is introduced.
  • Switching profiles invalidates all relevant static and dynamic Android Auto browse nodes so the prior profile's titles cannot remain visible.
  • Existing playback, route ownership, notification/media-button layout and #34/#36 behavior are unchanged.
  • JVM/unit coverage pins root order, series ordering, artwork metadata construction, profile selection semantics and cross-profile invalidation.
  • Physical Android Auto acceptance verifies root order, covers, profile switching, and stale-row behavior on the owner's projected head unit.

Ownership

Primary: Android System & Auto Agent.

Required review lenses:

  • Library & Sync Agent for series recency data/artwork source and profile-scoped library truth;
  • Playback & Lifecycle Agent for the existing progress-flush/pause/profile-switch contract;
  • Security & Privacy Agent for profile lock and artwork URI exposure;
  • Test & Acceptance Agent for projected Android Auto acceptance.

Documentation

The settled product choices in this issue are recorded in docs/product-decisions.md. Implementation details and any technical architecture needed to satisfy them may be captured in an ADR, but an ADR must not silently change the product decision.

## Goal Replace the current Android Auto browse hierarchy with the settled four-destination home and add artwork/profile switching as a dedicated implementation slice. This is a **new issue and new PR**. Do not fold this work into #35 / PR #61. ## Definitive product decision The Android Auto root is, in this order: 1. **Continue** 2. **Series** 3. **Authors** 4. **Profiles** There is no general **Library** root in this design. ### Series ordering The Series destination is ordered by playback recency when BookWave has playback evidence: - series with playback activity are ordered by their most recent played/progress activity, newest first; - series without playback activity follow alphabetically; - ties use alphabetical order for determinism. Books inside a series keep the existing canonical series-sequence ordering from LIB-003. ### History / queue - **History is not part of the Android Auto browse library.** - Do not recreate History under another car browse destination. - The standard Android Auto Queue is not required. #35 owns suppressing it on the standard player surface. - Do not implement a synthetic History queue or synthetic player timeline. ### Artwork and presentation Android Auto browse rows should use artwork wherever BookWave has safe cached artwork: - book rows use the book cover; - series rows use a representative cached book cover; - author rows follow the existing LIB-002 artwork policy (confirmed portrait when available, cached representative cover as fallback); - missing/offline artwork degrades cleanly to the host placeholder. Continue, Series, Authors and the book rows reached through Series/Authors request the host's artwork-first grid/card content style. Profiles remains text-first/list-like so active, lock and account state stays legible. The automotive host owns the exact background, card chrome, spacing and typography. BookWave supplies its shipped teal platform accent where the host honours the app accent; this issue does not introduce a custom-drawn car background. Artwork supplied to Android Auto must be readable by the car/media host process, work from cached/offline state, must not initiate a fresh artwork network fetch on behalf of the host, and must never expose credentials or tokens in a URI. ### Profiles Profiles is a first-class Android Auto browse destination. - list the saved profiles using existing profile identity/display data and clearly mark the active profile; - selecting a different profile uses the existing AUTH-002 / PRODUCT_SPEC 6.5 atomic profile-switch behavior: flush progress, pause playback by default, change profile context atomically, invalidate the car browse tree, and restore the new profile's state paused; - switching from Android Auto must not bypass AUTH-005/profile locking. If a target profile requires an unlock that cannot be completed in the car surface, explain that the profile must be unlocked on the phone rather than exposing its library; - after a successful switch, no rows from the previous profile may remain visible through a subscribed/cached browse node. ## Current state to replace Current Android Auto root on `main` is: - Continue - Series - Authors - Library The Library subtree currently contains Chapters, History, Downloads, Recently added, Listen again, Discover and Audio output. This issue deliberately replaces that information architecture rather than adding another tab to it. ## Acceptance criteria - [ ] Root contains exactly Continue → Series → Authors → Profiles. - [ ] History is absent from the Android Auto browse tree. - [ ] The old Library root/subtree is no longer exposed through Android Auto. - [ ] Series order follows playback-recency-then-alphabetical semantics above. - [ ] Books inside each series retain canonical series sequence ordering. - [ ] Continue, Series and Authors request artwork-first grid/card presentation; Profiles remains list-like. - [ ] BookWave exposes its shipped teal platform accent without depending on a custom Android Auto background. - [ ] Continue/book rows render cached cover artwork on Android Auto when available. - [ ] Series rows render a representative cached cover. - [ ] Author artwork follows LIB-002 and remains safe/offline-capable. - [ ] Host artwork reads do not trigger a new network fetch. - [ ] Artwork URIs are host-readable and contain no reusable credential material. - [ ] Profiles lists saved profiles and marks the active one. - [ ] A successful profile switch flushes/preserves progress and pauses by default per PRODUCT_SPEC 6.5. - [ ] A locked profile cannot be entered from Android Auto without satisfying existing lock policy; no lock bypass is introduced. - [ ] Switching profiles invalidates all relevant static and dynamic Android Auto browse nodes so the prior profile's titles cannot remain visible. - [ ] Existing playback, route ownership, notification/media-button layout and #34/#36 behavior are unchanged. - [ ] JVM/unit coverage pins root order, series ordering, artwork metadata construction, profile selection semantics and cross-profile invalidation. - [ ] Physical Android Auto acceptance verifies root order, covers, profile switching, and stale-row behavior on the owner's projected head unit. ## Ownership Primary: **Android System & Auto Agent**. Required review lenses: - **Library & Sync Agent** for series recency data/artwork source and profile-scoped library truth; - **Playback & Lifecycle Agent** for the existing progress-flush/pause/profile-switch contract; - **Security & Privacy Agent** for profile lock and artwork URI exposure; - **Test & Acceptance Agent** for projected Android Auto acceptance. ## Documentation The settled product choices in this issue are recorded in `docs/product-decisions.md`. Implementation details and any technical architecture needed to satisfy them may be captured in an ADR, but an ADR must not silently change the product decision.
Author
Owner

The definitive product decision for this issue is recorded as PD-001 in docs/product-decisions.md, introduced by docs-only PR #66. PR #66 establishes the decision ledger and records the settled Android Auto root/order, series sorting, artwork target, Profiles destination, and History/Queue non-goals. This issue remains open for the separate runtime implementation PR.

The definitive product decision for this issue is recorded as **PD-001** in `docs/product-decisions.md`, introduced by docs-only PR #66. PR #66 establishes the decision ledger and records the settled Android Auto root/order, series sorting, artwork target, Profiles destination, and History/Queue non-goals. This issue remains open for the separate runtime implementation PR.
Author
Owner

Physical Android Auto acceptance follow-up — 2026-09-20

The owner tested the new PD-001 browse home on the projected head unit.

Result

The Profiles destination rendered only the currently active profile even though multiple profiles are saved. The required behavior is to show all saved profiles so the driver can switch accounts from Android Auto.

Investigation

The saved-profile data source is not filtering to the active profile:

  • ProfileRepository.observeProfiles() is the same all-saved-profile source used by the phone profile switcher;
  • ProfileDao.observeProfiles() selects all profile rows;
  • #65's browse snapshot already fingerprints all saved profiles for Profiles invalidation.

The car rows were instead published with both isBrowsable=false and isPlayable=false. That left inactive profile rows without a valid media-hierarchy role even though they advertised the Use profile media-item command.

Fix on PR #71

PR #71 now publishes every saved profile as:

  • browsable = true;
  • playable = false;
  • no profile-library children;
  • inactive rows retain the existing Use profile custom media-item command;
  • switching still delegates to the existing atomic SwitchProfileUseCase and lock policy.

Regression coverage now uses two saved profiles and pins that both rows are published, the active row is marked active, and only the inactive row advertises the switch command.

Current fix head: 0e1087d2c7a5edc2814d011d0c4a4b32d4cfb2e6.

A fresh exact-head Forgejo PR verification has been dispatched; physical confirmation of the corrected multi-profile rendering remains required after the resulting build is installed.

## Physical Android Auto acceptance follow-up — 2026-09-20 The owner tested the new PD-001 browse home on the projected head unit. ### Result The Profiles destination rendered only the currently active profile even though multiple profiles are saved. The required behavior is to show all saved profiles so the driver can switch accounts from Android Auto. ### Investigation The saved-profile data source is not filtering to the active profile: - `ProfileRepository.observeProfiles()` is the same all-saved-profile source used by the phone profile switcher; - `ProfileDao.observeProfiles()` selects all profile rows; - #65's browse snapshot already fingerprints all saved profiles for Profiles invalidation. The car rows were instead published with both `isBrowsable=false` and `isPlayable=false`. That left inactive profile rows without a valid media-hierarchy role even though they advertised the `Use profile` media-item command. ### Fix on PR #71 PR #71 now publishes every saved profile as: - browsable = true; - playable = false; - no profile-library children; - inactive rows retain the existing `Use profile` custom media-item command; - switching still delegates to the existing atomic `SwitchProfileUseCase` and lock policy. Regression coverage now uses two saved profiles and pins that both rows are published, the active row is marked active, and only the inactive row advertises the switch command. Current fix head: `0e1087d2c7a5edc2814d011d0c4a4b32d4cfb2e6`. A fresh exact-head Forgejo PR verification has been dispatched; physical confirmation of the corrected multi-profile rendering remains required after the resulting build is installed.
Author
Owner

#65 profile-row fix verification

The physical-test follow-up is now verified on the exact PR head.

  • PR #71 head: 0e1087d2c7a5edc2814d011d0c4a4b32d4cfb2e6
  • Forgejo Actions run #187 / backend run 294: success
  • full verifyDebug: BUILD SUCCESSFUL in 8m 9s
  • playback detekt/ktlint: passed
  • playback unit tests: passed, including the new two-saved-profile regression
  • app lint / aggregate verification: passed
  • debug APK artifact: produced
  • PR remains mergeable against unchanged main

The remaining proof is physical Android Auto rendering: Profiles should now show every saved profile, with inactive rows offering the existing Use profile action.

## #65 profile-row fix verification The physical-test follow-up is now verified on the exact PR head. - PR #71 head: `0e1087d2c7a5edc2814d011d0c4a4b32d4cfb2e6` - Forgejo Actions run #187 / backend run 294: **success** - full `verifyDebug`: **BUILD SUCCESSFUL in 8m 9s** - playback detekt/ktlint: passed - playback unit tests: passed, including the new two-saved-profile regression - app lint / aggregate verification: passed - debug APK artifact: produced - PR remains mergeable against unchanged `main` The remaining proof is physical Android Auto rendering: Profiles should now show every saved profile, with inactive rows offering the existing `Use profile` action.
Author
Owner

Canonical acceptance staging — 2026-09-24

Reviewed main / acceptance APK source: 88ae231ddc01897d83e24968bed5443ea861aedd
Merged implementation: PR #71, accepted head 0e1087d2c7a5edc2814d011d0c4a4b32d4cfb2e6, merge commit 3516344c3b16b8b114b6037aa68ecb30fc25d2e4.
Exact-head CI: Forgejo run #187 / backend run 294 — success.
Current-main regression evidence: PR #89 exact head later passed run #270 with verifyDebug, 2606 tests / 0 failures, clean ktlint/detekt/Android Lint/Room schema; current-main push run #271 passed at 88ae231d....

Acceptance matrix — repository/automated claims

  • PROVEN — automated: root membership/order is exactly Continue → Series → Authors → Profiles, including with an empty library.
  • PROVEN — automated: no History browse destination and no old Library subtree are exposed. Retired IDs remain only as invalidation/eviction identities so stale host nodes can be cleared.
  • PROVEN — automated: Series with playback activity sort by newest activity first; ties/unplayed Series fall back to deterministic alphabetical ordering.
  • PROVEN — automated: books inside a Series retain the canonical LIB-003 numeric sequence order.
  • PROVEN — automated: representative Series/Author artwork is derived deterministically and absent artwork stays absent instead of inventing a source.
  • PROVEN — automated: Android Auto artwork URIs are opaque local content://…autoart/<token> capabilities and tests assert that server/source/token/credential material is not present in the URI.
  • PROVEN — repository/product decision: the exported artwork provider is the cross-process host-readable boundary; it is read-only, profile-scoped and token-gated. It materializes only from local/offline or Coil-cached sources with Coil 2.7.0's network policy disabled for the host request, so the host-artwork path is intentionally cache-only and does not initiate a fresh network fetch.
  • PROVEN — automated: Profiles maps all saved profiles, not only the active one. The regression test uses multiple saved profiles and asserts every row is browsable/non-playable so Android Auto hosts keep the rows visible.
  • PROVEN — automated: active profile is marked and inactive profiles expose the Use profile media-item command.
  • PROVEN — automated: AUTH-005 lock enforcement remains in SwitchProfileUseCase before playback handover or active-profile mutation. Locked profiles cannot be activated by the car command; the car receives a phone-unlock/permission-denied result.
  • PROVEN — automated: profile switching preserves the atomic ordering: outgoing playback handover/flush occurs while the outgoing profile is still active, then active context changes, then session restoration/refresh follows. Re-selecting the already-active profile does not tear playback down.
  • PROVEN — automated: profile-boundary invalidation evicts all static profile-scoped parents, retired parents and previously emitted dynamic parents, preventing old-profile subscribed/cached rows from surviving a switch.

Historical physical failure and why it is not accepted yet

The issue records the important post-implementation failure from 2026-09-20: projected Android Auto showed only the active profile even though multiple profiles were saved.

PR #71 then changed profile rows to be host-visible browsable/non-playable items and added the multi-profile regression test. That correction is automated-green, but there is no later projected-host evidence proving that the actual Android Auto host now renders all saved profiles. This specific failure must be physically re-tested.

Acceptance APK

Forgejo Build APK run #272 produced:

  • artifact bookwave-debug-0.10.6.1-2272
  • APK bookwave-debug-0.10.6.1-2272.apk
  • package org.homebord.bookwave.debug
  • exact source 88ae231ddc01897d83e24968bed5443ea861aedd
  • signing certificate verified against the configured BookWave keystore
  • no redundant verifyDebug rerun in the artifact workflow.

Residual projected Android Auto acceptance

Use at least two saved profiles.

  1. Note the currently active profile.
  2. Connect projected Android Auto.
  3. Verify root order exactly: Continue → Series → Authors → Profiles.
  4. Open Continue, Series and Authors; verify representative cover artwork where the source is already cached/offline.
  5. Open Profiles.
  6. Verify all saved profiles are visible.
  7. Verify the active profile is visibly distinguishable.
  8. Select an unlocked inactive profile via its switch action.
  9. Verify the existing switch semantics: outgoing playback is handed over/paused as applicable and the new profile becomes active.
  10. Verify the new profile's browse data appears.
  11. Verify titles/Series/Authors/Continue rows from the previous profile do not remain in cached/subscribed nodes.
  12. If a locked profile exists, attempt it and verify Android Auto does not bypass the lock; it must require phone-side unlock instead.

Host-dependent matrix:

  • STILL REQUIRES PHYSICAL TEST: corrected multi-profile rows are actually rendered by the projected host.
  • STILL REQUIRES PHYSICAL TEST: active/inactive presentation and switch action are usable on that host.
  • STILL REQUIRES PHYSICAL TEST: profile switch refreshes the projected browse tree with no stale prior-profile rows.
  • STILL REQUIRES PHYSICAL TEST: cached artwork is rendered where available by the real host.
  • STILL REQUIRES PHYSICAL TEST: locked-profile interaction is not misleading on the host, while the domain lock boundary itself is already automated-proven.

If #36 interrupts playback during this test, log it as an external #36 observation rather than a #65 failure unless the browse/profile contract itself is wrong.

Result

READY FOR PHYSICAL ACCEPTANCE

## Canonical acceptance staging — 2026-09-24 **Reviewed main / acceptance APK source:** `88ae231ddc01897d83e24968bed5443ea861aedd` **Merged implementation:** PR #71, accepted head `0e1087d2c7a5edc2814d011d0c4a4b32d4cfb2e6`, merge commit `3516344c3b16b8b114b6037aa68ecb30fc25d2e4`. **Exact-head CI:** Forgejo run #187 / backend run 294 — success. **Current-main regression evidence:** PR #89 exact head later passed run #270 with `verifyDebug`, **2606 tests / 0 failures**, clean ktlint/detekt/Android Lint/Room schema; current-main push run #271 passed at `88ae231d...`. ### Acceptance matrix — repository/automated claims - **PROVEN — automated:** root membership/order is exactly **Continue → Series → Authors → Profiles**, including with an empty library. - **PROVEN — automated:** no History browse destination and no old Library subtree are exposed. Retired IDs remain only as invalidation/eviction identities so stale host nodes can be cleared. - **PROVEN — automated:** Series with playback activity sort by newest activity first; ties/unplayed Series fall back to deterministic alphabetical ordering. - **PROVEN — automated:** books inside a Series retain the canonical LIB-003 numeric sequence order. - **PROVEN — automated:** representative Series/Author artwork is derived deterministically and absent artwork stays absent instead of inventing a source. - **PROVEN — automated:** Android Auto artwork URIs are opaque local `content://…autoart/<token>` capabilities and tests assert that server/source/token/credential material is not present in the URI. - **PROVEN — repository/product decision:** the exported artwork provider is the cross-process host-readable boundary; it is read-only, profile-scoped and token-gated. It materializes only from local/offline or Coil-cached sources with Coil 2.7.0's network policy disabled for the host request, so the host-artwork path is intentionally cache-only and does not initiate a fresh network fetch. - **PROVEN — automated:** Profiles maps **all saved profiles**, not only the active one. The regression test uses multiple saved profiles and asserts every row is browsable/non-playable so Android Auto hosts keep the rows visible. - **PROVEN — automated:** active profile is marked and inactive profiles expose the `Use profile` media-item command. - **PROVEN — automated:** AUTH-005 lock enforcement remains in `SwitchProfileUseCase` before playback handover or active-profile mutation. Locked profiles cannot be activated by the car command; the car receives a phone-unlock/permission-denied result. - **PROVEN — automated:** profile switching preserves the atomic ordering: outgoing playback handover/flush occurs while the outgoing profile is still active, then active context changes, then session restoration/refresh follows. Re-selecting the already-active profile does not tear playback down. - **PROVEN — automated:** profile-boundary invalidation evicts all static profile-scoped parents, retired parents and previously emitted dynamic parents, preventing old-profile subscribed/cached rows from surviving a switch. ### Historical physical failure and why it is not accepted yet The issue records the important post-implementation failure from **2026-09-20**: projected Android Auto showed **only the active profile** even though multiple profiles were saved. PR #71 then changed profile rows to be host-visible browsable/non-playable items and added the multi-profile regression test. That correction is automated-green, but there is no later projected-host evidence proving that the actual Android Auto host now renders all saved profiles. This specific failure must be physically re-tested. ### Acceptance APK Forgejo **Build APK run #272** produced: - artifact `bookwave-debug-0.10.6.1-2272` - APK `bookwave-debug-0.10.6.1-2272.apk` - package `org.homebord.bookwave.debug` - exact source `88ae231ddc01897d83e24968bed5443ea861aedd` - signing certificate verified against the configured BookWave keystore - no redundant `verifyDebug` rerun in the artifact workflow. ### Residual projected Android Auto acceptance Use **at least two saved profiles**. 1. Note the currently active profile. 2. Connect projected Android Auto. 3. Verify root order exactly: **Continue → Series → Authors → Profiles**. 4. Open Continue, Series and Authors; verify representative cover artwork where the source is already cached/offline. 5. Open Profiles. 6. Verify **all saved profiles** are visible. 7. Verify the active profile is visibly distinguishable. 8. Select an unlocked inactive profile via its switch action. 9. Verify the existing switch semantics: outgoing playback is handed over/paused as applicable and the new profile becomes active. 10. Verify the new profile's browse data appears. 11. Verify titles/Series/Authors/Continue rows from the previous profile do **not** remain in cached/subscribed nodes. 12. If a locked profile exists, attempt it and verify Android Auto does not bypass the lock; it must require phone-side unlock instead. Host-dependent matrix: - **STILL REQUIRES PHYSICAL TEST:** corrected multi-profile rows are actually rendered by the projected host. - **STILL REQUIRES PHYSICAL TEST:** active/inactive presentation and switch action are usable on that host. - **STILL REQUIRES PHYSICAL TEST:** profile switch refreshes the projected browse tree with no stale prior-profile rows. - **STILL REQUIRES PHYSICAL TEST:** cached artwork is rendered where available by the real host. - **STILL REQUIRES PHYSICAL TEST:** locked-profile interaction is not misleading on the host, while the domain lock boundary itself is already automated-proven. If #36 interrupts playback during this test, log it as an external #36 observation rather than a #65 failure unless the browse/profile contract itself is wrong. ## Result **READY FOR PHYSICAL ACCEPTANCE**
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#65
No description provided.