screentinker/docs/109-android-pip-visibility.md

# #109 — Android PiP overlay not painting over YouTube

## Symptom

`POST /api/pip` returns `sent: 1`, the overlay's title text appears in
`uiautomator dump` (so the view IS attached, laid out, and on-screen in the
accessibility tree), but **nothing paints on the panel**. The repro is while
**YouTube** content is playing (`R.id.youtubeWebView`).

The PiP title and its media are siblings in one box, so "title in the dump but
nothing on screen" means the **whole box is attached-but-not-painting**, not a
media-only failure.

## The three candidate causes

| # | Cause | What the magenta-box instrumentation shows |
|---|-------|--------------------------------------------|
| 1 | **Surface occlusion** — the YouTube WebView's hardware video plane composites *above* the in-tree overlay | magenta box visible over a static image but **not** over YouTube |
| 2 | **Orientation transform** — `rootView`'s rotation/translation pushes the box off-screen | box `getGlobalVisibleRect()` empty / outside the 1920×1080 panel |
| 3 | **Measure / visibility** — `pipLayout` not laid out, 0-size, or `GONE` on attach | box not shown / 0-size / `pipLayout` `childCount==0` |

## Phase 1 — Instrumentation (shipped, default OFF)

A `pipDebug` flag (`PipOverlay.pipDebug`, default `false`) is toggled over the
**existing** `device:command` transport — no new transport invented:

```
device:command { "type": "pip_debug", "payload": { "enabled": true } }
```

When on, `PipOverlay.show()`:

- paints the box **solid magenta** (`#CCFF00FF`) with an 8px magenta border and
  renders the media on top, so the **box paints even if the media never loads**;
- posts a one-shot Runnable that logs, over `device:log` tag **`pip`**:
  - `box` width/height, `getGlobalVisibleRect()`, `isShown`
  - `pipLayout` width/height/visibility/childCount + its index in its parent
  - `rootView` rotation / translationX / translationY / scaleX / `isHardwareAccelerated`
  - `youtubeWebView` visibility + `getGlobalVisibleRect()`
- `loadImageInto` also logs on **success** (bitmap w/h), not just failure.

`pipDebug` is left present and default-false.

## Phase 2 — Reproduce

Enable remote debug logging from the dashboard (so `device:log` is forwarded),
then enable the PiP debug flag, then fire a PiP under each content type and read
the `pip`-tagged lines.

**(a) PiP over a static image**

1. Assign a single still image to the device; let it display.
2. `device:command {type:"pip_debug",payload:{enabled:true}}`.
3. `POST /api/pip {device_id, type:"image", uri:"https://…/x.png", position:"top-right", duration:30}`.
4. Capture the `pip dbg …` lines + a screenshot.

**(b) PiP over YouTube** (the failing repro)

1. Assign a YouTube item; let it play in `R.id.youtubeWebView`.
2. (debug already enabled.)
3. Same `POST /api/pip` as above.
4. Capture the `pip dbg …` lines + a screenshot.

Decision table (compare a-vs-b):

- magenta box visible over the image but **NOT** over YouTube → **(1) surface occlusion**
- box `globalRect` empty / off the 1920×1080 panel → **(2) orientation**
- box not shown / 0-size / not laid out → **(3) measure/visibility**

> Note: on-device capture must be done on the real signage hardware (Fire TV /
> Android TV). The WebView hardware-video-overlay behaviour that drives cause (1)
> is device- and WebView-version-specific and does **not** reproduce on a stock
> emulator, so it cannot be captured from a CI/dev box with no device attached.

## Which cause — and the fix

By elimination the symptom points at **(1) surface occlusion**:

- It is **YouTube-specific** (a WebView playing HTML5 video). An orientation (2)
  or measure (3) fault would fail over images too, but the overlay is only
  reported broken over YouTube.
- The repro is **landscape** (the default orientation → `rotation = 0`, no
  translation), so the box cannot be transformed off-screen → not (2).
- The title shows with **real on-screen bounds** in `uiautomator dump`, so the
  box is laid out at non-zero size and `pipLayout` is `VISIBLE` → not (3).

That leaves the video surface compositing above the in-tree overlay.

### Fix (cause 1) — file/line

`pipLayout` previously lived as the **last child of `rootLayout`**, i.e. in the
**same compositing band** as `R.id.youtubeWebView`; the WebView's playing video
surface drew over it. The fix moves the PiP layer to a **top-level view above the
WebView** (the task's option 1a):

- **`MainActivity.onCreate`** (`android/app/src/main/java/com/remotedisplay/player/MainActivity.kt`)
  reparents `R.id.pipLayout` out of `rootLayout` up to the window content
  (`android.R.id.content`), as a sibling drawn **after** `rootLayout` → it
  composites above the WebView.
- **`MainActivity.mirrorTransformToPip()`** copies `rootView`'s current size +
  rotation/translation/scale onto `pipLayout` after every transform change
  (`applyOrientation` / `applyWallTransform`), so corner positions still track the
  rotated content — mirroring how the web/Tizen players apply the same transform
  to `#pip` as to `#stage`.
- **`PipOverlay.show()`** (`…/player/PipOverlay.kt`) raises the layer and forces a
  layout/redraw on attach (`bringToFront()` + `requestLayout()` + `invalidate()`),
  which also covers the cause-(3) measure/visibility path.
- The remote-view screenshot source moved from `rootView` to `captureRoot`
  (the window content) so the reparented PiP is still captured.

### Server dispatch logging

`POST /api/pip` and the clear handler (`server/routes/pip.js`) now log one
concise `[pip] …` line each (target kind + id + sent/offline counts) so
`journalctl` shows PiP activity.

## Emulator validation (landscape + portrait)

The fix was exercised end-to-end on an Android emulator (pixel10, API 34) paired
to an isolated local server, with a YouTube item playing in
`R.id.youtubeWebView`:

- **No crash** — provisioning → `MainActivity` → playback ran clean; the reparent
  + `mirrorTransformToPip()` executed (`Applied orientation: landscape … / portrait
  (rotation=90.0, swap=true)`).
- **PiP composites above the playing YouTube video** — a `POST /api/pip` box
  (magenta via `background_color`) rendered on top of the live video frame
  (center and top-right placements both correct, 4% inset honoured).
- **Clear** removed the overlay cleanly; the video kept playing.
- **Portrait** — the overlay rotated *with* the rotated stage and stayed inside
  the frame (not off-screen), confirming the transform mirror.
- Server `[pip] show … 1 sent` / `[pip] clear (all) …` dispatch lines appeared.

Caveat (unchanged): the emulator's WebView composites video **inline**, so it
confirms the reparent renders correctly and doesn't regress, but it does **not**
reproduce the Fire TV / Android TV hardware-overlay punch-through that is the
strongest form of cause (1). That still needs the real signage device — use the
`pipDebug` magenta box there to confirm.

### Follow-up bug found in emulator testing: image PiPs never painted the image

Verifying an **image** PiP (a QR PNG) surfaced a separate, pre-existing defect
(present on `main`, unrelated to the occlusion reparent): the image area was
always blank — only the box background + title showed. Root cause in
`PipOverlay.show()`: `teardown()` clears `current` to null, then `loadImageInto`
captured `token = current` (null) as its drop-if-replaced guard, but `current`
was only set to the new `pip_id` *after* the media was built. The decode finishes
on a background thread and posts back **after** `show()` returns — so the guard
`token != current` (null ≠ pip_id) was always true and **every decoded bitmap was
dropped**. (Web PiPs and the box/title were unaffected, which masked it.)

Fix: set `current = pip_id` **before** building the media (so `loadImageInto`'s
token matches). Confirmed on the emulator — the QR now renders in the PiP box
over both a static image and live YouTube.

### Content types verified on the emulator (over live YouTube)

- **image** PiP (a QR PNG) — renders after the token-ordering fix above.
- **web** PiP (an HTML page) — loads in the PiP WebView and **executes JS** (a
  page that stamps `JS OK · <time>` into the DOM rendered correctly over the
  playing video); composites above the main YouTube WebView. No code change
  needed — web PiPs never went through the broken image path.
- title + `background_color` box — paints above the video (the original cause-1
  fix).
- **`close_button: true`** — the server already forwarded this flag
  (`routes/pip.js`) and it's in `openapi.yaml`, but no player rendered it (Tizen
  deferred "close-button focus" as non-MVP; the web player has none). Implemented
  on Android: a tappable ✕ floats at the box's top-right (a sibling of the box, so
  it isn't clipped by the outline or dimmed by `opacity`) and clears THIS overlay
  (id-matched) on tap. Only the ✕ is clickable; the rest of the full-screen
  `pipLayout` stays touch-transparent so taps fall through to the content. Verified
  on the emulator — tapping it removed the overlay and the video kept playing.
  Parity note: the web/Tizen players still don't implement `close_button`; D-pad
  focus of the ✕ on non-touch TV hardware is intentionally not wired (MVP =
  touch/pointer only, matching the Tizen focus deferral).

## If the magenta box is STILL hidden over YouTube on the test device

Then it is the stronger form of cause (1): the WebView places its video on a
**hardware overlay / `SurfaceView` plane** that no in-window view can beat.
Escalate (task options 1b/1c), keeping the first that works on the device:

- host the PiP box in a `SurfaceView` with `setZOrderMediaOverlay(true)` /
  `setZOrderOnTop(true)`, or a small `WindowManager` panel sub-window; or
- when YouTube is active, render the PiP via the in-tree image path so no
  competing WebView video surface is involved.

The `pipDebug` instrumentation stays in place to make that determination.