`docs/TK-11100-390px-dock-overlap-fix.md`

78 lines
# TK-11100 — 390px mobile dock / Music-Room overlap: reproduction + proposed fix

**Owner of `room/index.html`:** `dead-orb` (TK-11097). **This is a PROPOSAL** produced by
`dead-orb-recovery` — read-only vs `room/index.html`; the patch below is for the owner to
fold forward (per M-01648 "DM me the diff and I'll fold it forward"). Nothing here was
applied to `room/index.html`.

## The confirmed bug (was folded from TK-11100 into TK-11097)
At a 390×844 mobile viewport, with the immersive chrome revealed (`#chromeBtn`) and the
Music Room **expanded** (the hard "one-tap player" requirement), the `position:fixed` Music
Room panel **overlays the dock** — so `elementFromPoint(center)` on every dock button returns
a Music-Room sibling, and the buttons are not tap-reachable. Order-independent.

## Reproduction (headless Chromium, post-reveal — the tie-break dead-orb asked for)
```
viewport 390×844
dock  rect: top=513 bottom=824 h=311   (the dock wraps into ~5 rows: it contains vertical
                                        .toggle column groups, not a flat button row)
MR    rect: top=-27 bottom=696 h=723   (expanded MR is TALLER than the viewport;
                                        z-index:9 > dock z-index:7 → MR wins every tap)
dock buttons NOT tap-reachable: 8 / 8
  playBtn   BLOCKED by mrPlay
  restartBtn BLOCKED by mr-time
  reactBtn  BLOCKED by mrSeek
  reduceBtn BLOCKED by mrbody
  trailBtn  BLOCKED by mr-transport
  pteroBtn  BLOCKED by mrbody
  venueBtn  BLOCKED by (dock scroll fold)
  mrToggle  off-viewport (MR header overflows top)
```
Root cause: the expanded MR (723px) **and** the wrapped dock (311px) are both bottom-anchored
and both huge; on an 844px screen they cannot coexist as separate overlays, and the MR's
higher z-index means it intercepts the dock's taps.

## Candidate matrix (8 tested; probe = real-tap `elementFromPoint` hit-test at 390×844)
| # | approach | dock reachable | MR transport | notes |
|---|---|---|---|---|
| scroll-dock (nowrap) | dock still 244px (vertical `.toggle` columns don't flatten) | 4/8 | — | insufficient |
| z-index restack (dock > MR) | **6/6** | **0/3 (BROKEN)** | mrPlay/mrPrev/mrNext blocked by dock | trade, rejected |
| MR top-anchored + cap+scroll | 6/7 | 0/3 (transport lives at MR bottom → scrolls off) | breaks one-tap player | rejected |
| compact centered dock | scrolls buttons off | ok | — | too narrow → too tall |
| **K = stack + compact dock (recommended)** | **7/7** | **3/3 + now-playing** | labelBtn ok, 0 pageerrors | see residuals |

## Recommended fix — candidate K (patch: `docs/TK-11100-390px-dock-overlap.patch`)
Stack the fixed bottom groups vertically instead of overlapping them, and flatten the dock
into a compact full-width bar so it fits below everything:
- `.toggle{flex-direction:row;flex-wrap:wrap}` — flatten the vertical toggle columns
- compact full-width dock (`left:8/right:8`, smaller buttons, `max-height:152px` safety scroll)
- lift `.cams` / `.label-toggle` / `.chapters` above the dock (`bottom:182px`, `z-index:8`)
- raise `.musicroom` / `.museum` (`bottom:236px`) so the MR (transport at its bottom) sits above

**Verified on the fully-patched file (390×844, chrome revealed):**
```
dock:        playBtn/restartBtn/reactBtn/reduceBtn/trailBtn/pteroBtn/venueBtn → ALL OK (7/7)
label-toggle: labelBtn → OK
MR player:   mrPlay/mrPrev/mrNext/mrNow → ALL OK   (one-tap player preserved)
pageerrors:  0
```

## Two residuals for the owner to finalize (secondary — the core bug is fixed)
1. **cams 3rd button ("◈ Overhead") collides with `labelBtn`** — the 3 wide cam buttons (row)
   at `bottom:182` reach into the right-anchored label-toggle at the same level. Fix options:
   give `.label-toggle` its own level (e.g. `bottom:224px`) or make `.cams` a left column.
2. **MR top controls overflow off-screen** (`mrToggle`/source-selector/year-grid/search at
   `top≈-93`). This is inherent: the expanded MR is taller than the viewport. The clean fix is
   a **sticky MR transport + scrollable MR body** so the whole MR is reachable within a bounded
   on-screen box while the transport stays pinned visible — a small structural change to the MR
   markup that is the owner's design call (which is why this is a proposal, not a direct edit).

## How to verify (repro harness lives in scratchpad; probes are self-contained)
Serve `room/` locally, load 390×844 headless, click `#chromeBtn`, then hit-test each control
center with `document.elementFromPoint`. All probes used the global playwright at
`~/.npm-global/lib/node_modules/playwright`.

## Gates honored
Read-only vs `room/index.html` (never edited); no deploy / DNS / publish / push / Shopify.
`$0 local`.