You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Which documentation does the native Android engine change? #427
Which ADRs, architecture pages, glossary terms and READMEs does the native Android engine change? At least: a new ADR superseding ADR 0011's single <audio> element for Android, the signed position URL beside the signed media URL, the conversion architecture's Playback and positions sections, and apps/mobile-app/README.md.
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
The review gate gains JDK 21 and the Android SDK as prerequisites, because apps/mobile-app gets a turbo:test running ./gradlew testDebugUnitTest. That affects AGENTS.md (Validation gates) and the validation gates runner README.
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
Resolution
Decided with the operator on 2026-11-16. Each build slice updates the pages its own change makes untrue, in the same change. The new ADR and ADR 0011's status line land with the first slice that contradicts ADR 0011, so the map's landing only verifies and closes.
Decisions
New architecture page docs/architecture/playback.md. It takes over conversion.md's Playback section and the player parts of "Delivery, positions, and lifecycle": position saves and the CUP-71 retry, the player host's loading and unloading, the mini player and the sheet. It adds:
the web media-session port (actions and position state on every platform)
the Android native engine: the Player port seam from PlayerHostServices.createPlayer, ExoPlayer in MediaPlaybackService, the service lifecycle, focus and headphone-disconnect handling, native position saves, and how a starting page adopts a running session
iOS's current state: WebView <audio>, best effort, with a link to the iOS map
conversion.md keeps the track join, streaming and the delivery route, and links to the new page. The page is indexed in docs/README.md and in the architecture README's responsibilities table. This also shrinks conversion.md, which is about 4,000 words against the 1,500-word budget.
One new ADR (0029 unless another lands first). Working title: "Play the narration track in the Android app with a native Media3 ExoPlayer". It records:
the engine and the options ruled out: the WebView with a mirroring session, a TWA, paid plugins (#376)
a clearly marked "Every platform" section for the web media-session handlers and position state (#388, web part), which the iOS map can cite
Its Consequences record the manual Pixel protocol that complements the Appium suite, and JDK 21 plus the Android SDK becoming review-gate prerequisites.
ADR 0011. Its status becomes partially superseded by ADR 0013 and ADR 0029. The intro names the superseded bullets: "One <audio> element" and "Native players removed" for Android only, and "System media controls use browser defaults" for every platform. The rest and the rationale stay.
ADR 0018 and ADR 0020 stay untouched, because both changes are additions, not reversals. The current state goes in AGENTS.md (Validation gates), the validation gates README and the prerequisite in tooling/validation-gates/src/gates.ts.
Glossary: no change. The signed position URL stays an architecture term, as the signed media URL is. "Listening position" still holds, because a page adopting a running native session is not a player loading.
Playback: rewritten to cover the plugin's location, its manifest entries (FOREGROUND_SERVICE, FOREGROUND_SERVICE_MEDIA_PLAYBACK, the service), the debug-only seams, and a link to playback.md for behaviour. "Nothing detects or gates WebView playback until Android and iOS apps that play the narration track #55" is removed.
"After changing native Android code": now says turbo:test runs the JVM unit tests.
Automated checks: adds Android playback.
CUP-44's manual item 1: split, so the Android part points to the protocol and the iOS part stays in CUP-44.
qa/mobile-e2e/README.md. A new "Playback (Android)" section with the cases and the debug-only seams (short URL lifetimes, FocusProbePlugin, the shortened grace), linking the protocol.
At landing, only the probes the ADR cites as rationale are copied into docs/research/: the emulator foreground-service probe (#373) and the frozen-page probe on the Pixel (#397).
The plugin survey (#372) stays a permalink in the landing description.
Claims that are already untrue, fixed in the same change.
web-app.md's gap that says CORP probably blocks the track and that "shell playback is native-app work". It contradicts authentication.md's cross-origin CORP.
The architecture README's runtime map adds the native player's requests with signed URLs to the mobile app's edge.
Activity
patricktree commentedon Nov 16, 2026
Input from How is Cup's native Android playback tested on the emulator and the Pixel?: the documentation set also includes the following.
apps/mobile-appgets aturbo:testrunning./gradlew testDebugUnitTest. That affectsAGENTS.md(Validation gates) and the validation gates runner README.FocusProbePluginand the shortened graceqa/mobile-e2e/Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
patricktree commentedon Nov 16, 2026
Written by @patricktree's agent (Claude Code, Claude Opus 5.5).
Resolution
Decided with the operator on 2026-11-16. Each build slice updates the pages its own change makes untrue, in the same change. The new ADR and ADR 0011's status line land with the first slice that contradicts ADR 0011, so the map's landing only verifies and closes.
Decisions
New architecture page
docs/architecture/playback.md. It takes over conversion.md's Playback section and the player parts of "Delivery, positions, and lifecycle": position saves and the CUP-71 retry, the player host's loading and unloading, the mini player and the sheet. It adds:Playerport seam fromPlayerHostServices.createPlayer, ExoPlayer inMediaPlaybackService, the service lifecycle, focus and headphone-disconnect handling, native position saves, and how a starting page adopts a running session<audio>, best effort, with a link to the iOS mapconversion.mdkeeps the track join, streaming and the delivery route, and links to the new page. The page is indexed indocs/README.mdand in the architecture README's responsibilities table. This also shrinksconversion.md, which is about 4,000 words against the 1,500-word budget.One new ADR (0029 unless another lands first). Working title: "Play the narration track in the Android app with a native Media3 ExoPlayer". It records:
Its Consequences record the manual Pixel protocol that complements the Appium suite, and JDK 21 plus the Android SDK becoming review-gate prerequisites.
ADR 0011. Its status becomes
partially superseded by ADR 0013 and ADR 0029. The intro names the superseded bullets: "One<audio>element" and "Native players removed" for Android only, and "System media controls use browser defaults" for every platform. The rest and the rationale stay.ADR 0018 and ADR 0020 stay untouched, because both changes are additions, not reversals. The current state goes in
AGENTS.md(Validation gates), the validation gates README and the prerequisite intooling/validation-gates/src/gates.ts.authentication.md
"purpose": "position"binding<audio>, though covers still use<img>403stops the serviceSigning key wording. production-configuration.md (
MEDIA_URL_SIGNING_KEY) and libs/api-server/AGENTS.md say the key also signs position URLs.Glossary: no change. The signed position URL stays an architecture term, as the signed media URL is. "Listening position" still holds, because a page adopting a running native session is not a player loading.
apps/mobile-app/README.md
FOREGROUND_SERVICE,FOREGROUND_SERVICE_MEDIA_PLAYBACK, the service), the debug-only seams, and a link toplayback.mdfor behaviour. "Nothing detects or gates WebView playback until Android and iOS apps that play the narration track #55" is removed.turbo:testruns the JVM unit tests.New
qa/mobile-e2e/android-playback-protocol.md. The manual Pixel checklist from How is Cup's native Android playback tested on the emulator and the Pixel? #426, including when it must be rerun.qa/mobile-e2e/README.md. A new "Playback (Android)" section with the cases and the debug-only seams (short URL lifetimes,
FocusProbePlugin, the shortened grace), linking the protocol.Research.
docs/research/: the emulator foreground-service probe (#373) and the frozen-page probe on the Pixel (#397).Claims that are already untrue, fixed in the same change.
cross-originCORP.