From f3de5b70ffe07f894fb6476029012c9ae7902086 Mon Sep 17 00:00:00 2001
From: ducoterra <git@ducoterra.net>
Date: Sun, 1 Nov 2026 19:55:54 -0500
Subject: [PATCH] docs(agent): phase 04 - reachable share CTA at narrow widths

The Share button on /mirror is unclickable below ~700px and below the
fold in short windows. Measured with elementFromPoint on Chromium:

  320x568  stage 288x180  button 187px past the stage bottom  hit=H2
  390x844  stage 358x224  button 113px past                   hit=LABEL
  480x800  stage 448x280  button  36px past                   hit=#share-link
  900x480  stage 868x543  inside the stage, below the viewport hit=null

Root cause: .stage is display:grid with place-items:center, so <video>,
.placeholder and .livetag occupy three stacked rows rather than one
overlay cell. An idle <video> is intrinsically 300x150, so the
placeholder always starts at stage.top + 151 and runs out of the
overflow:hidden box; aspect-ratio 16/10 with no min/max height then
clips it when narrow and overshoots the viewport when short.

#stop measures clickable everywhere (the placeholder is hidden when
live), so the fix is scoped to the idle stage.

Phase: one-cell stage, floor + ceiling + scroll escape, a 12-viewport
clickability sweep (idle and live), and stylesheet guards.

LLM-Generated: true
---
 .../todo/04_reachable_share_cta/00_phase.md   | 133 ++++++++++++++++++
 .../01_one_cell_stage.md                      |  79 +++++++++++
 .../02_size_the_stage_for_real_viewports.md   |  88 ++++++++++++
 .../03_reachable_cta_e2e.md                   |  91 ++++++++++++
 .../04_css_guard_and_docs.md                  |  76 ++++++++++
 5 files changed, 467 insertions(+)
 create mode 100644 .agents/phases/todo/04_reachable_share_cta/00_phase.md
 create mode 100644 .agents/phases/todo/04_reachable_share_cta/01_one_cell_stage.md
 create mode 100644 .agents/phases/todo/04_reachable_share_cta/02_size_the_stage_for_real_viewports.md
 create mode 100644 .agents/phases/todo/04_reachable_share_cta/03_reachable_cta_e2e.md
 create mode 100644 .agents/phases/todo/04_reachable_share_cta/04_css_guard_and_docs.md

diff --git a/.agents/phases/todo/04_reachable_share_cta/00_phase.md b/.agents/phases/todo/04_reachable_share_cta/00_phase.md
new file mode 100644
index 0000000..386a490
--- /dev/null
+++ b/.agents/phases/todo/04_reachable_share_cta/00_phase.md
@@ -0,0 +1,133 @@
+# Phase 04 — The Share button must always be clickable
+
+**Source:** user request in chat — "the share button is cut off by the preview-stage, I can't click it in narrower view widths."
+**Story:** n/a
+**Context:** `src/mirror/static/app.css` `.share` / `.stage` / `.placeholder` / `.btn.big` (the `/* share */` block, ~L220–250), `src/mirror/static/mirror.html` (`#preview-stage` > `#preview`, `#placeholder` > `#start`, `#livetag`), `tests/test_app.py::TestStylesheet`, `tests/e2e/`
+
+## Objective
+
+`#start` ("Share my screen") is reachable and clickable at every viewport a
+person might realistically open `/mirror` on — measured from 320×568 to 1920×1080,
+and on short windows like 900×480. Today it is not, and this is not a cosmetic
+wrinkle: a sharer on a phone, a narrow side-by-side window, or a small laptop
+window **cannot start sharing at all**.
+
+## Measured on the reference host (Chromium, `channel="chromium"`, `http://127.0.0.1`)
+
+| Viewport | `#preview-stage` box | `#start` vs the stage box | `document.elementFromPoint(colour of button centre)` |
+|---|---|---|---|
+| 320×568 | 288×180 | button bottom **187 px below** the stage | `H2` — not the button |
+| 360×640 | 328×205 | 132 px below | the panel's `#name` input |
+| 390×844 | 358×224 | 113 px below | a `LABEL` |
+| 480×800 | 448×280 | 36 px below | `#share-link` |
+| 700×900 | 668×418 | inside | `#start` ✅ |
+| 900×480 | 868×543 | inside the stage, **below the viewport** | `null` |
+| 1280×450 | 902×564 | inside, **below the viewport** | `null` |
+
+Two independent failure modes, and the diagnosis is exact:
+
+1. **The stage is a two-row grid, not an overlay.** `.stage` is
+   `display: grid; place-items: center`, and its children — `<video id="preview">`,
+   `.placeholder`, `.livetag` — are three grid items, so they occupy three stacked
+   rows. `place-items: center` centres each item *in its own row*; it does not put
+   them in one cell. A `<video>` with no `srcObject` has an intrinsic **300×150**
+   box, so it reserves ~150 px and the placeholder starts at a constant
+   `stage.top + 151` at *every* width. `.livetag` escaped this because it is
+   `position: absolute`; `.placeholder` never was.
+2. **The stage's height is a function of its width with no floor and no ceiling.**
+   `aspect-ratio: 16 / 10` makes the box 180 px tall at 320 px wide while the
+   stacked content needs ~151 + 240 px, and `.stage { overflow: hidden }` (needed
+   for the rounded corners over live video) clips the remainder silently — with
+   no scroll container to reach it. On a short, wide window the same rule makes
+   the box *taller than the viewport* (543 px in a 480 px window), pushing the CTA
+   below the fold.
+
+For scale, the placeholder's own content height measures **240 px at 320 px wide**
+and **189 px at ≥480 px**.
+
+## The live state is not affected (verified, keep it that way)
+
+With a share running, `#placeholder` is `hidden`, the stack collapses, and
+`#stop` measures clickable at 320×568, 390×844 and 1280×450 (`hit_stop: true`).
+This phase must not change that.
+
+## Dependencies
+
+- `03_audio_share` (todo) — the preceding phase by number; no functional
+  dependency, but it and `01_keyboard_kiosk_control` both edit `app.css`. Keep
+  this phase's diff inside the `/* share */` block so the three never conflict.
+
+## Boundaries (explicitly out of scope)
+
+- No redesign of `/mirror`, no new markup for the stage, no JS/behaviour change —
+  `share.js` is not part of this fix.
+- `/watch` is untouched: `#watch-stage` is `position: fixed; inset: 0` with no
+  `aspect-ratio`, and `.tile` genuinely wants its stacked rows.
+- No breakpoint framework, no CSS preprocessor, no new dependency, no external
+  asset (PLAN A9/A10 are locked).
+
+## Tasks
+
+1. `01_one_cell_stage.md` — make the stage a single grid cell so the placeholder
+   overlays the video the way the markup intends.
+2. `02_size_the_stage_for_real_viewports.md` — a floor and a ceiling for the box,
+   and an escape hatch so content taller than the stage can never be unreachable.
+3. `03_reachable_cta_e2e.md` — the viewport sweep that proves the button is
+   clickable, idle and live.
+4. `04_css_guard_and_docs.md` — the stylesheet guard that stops the two-row grid
+   coming back, and the documentation pass.
+
+## Testing & Quality
+
+- Unit/integration for all new logic: this phase adds no Python logic, so its
+  "unit" layer is a static stylesheet guard in `tests/test_app.py::TestStylesheet`
+  (regex over `app.css`, matching the style of `test_hidden_always_means_gone` and
+  `test_no_rule_reintroduces_a_conflicting_display_for_hidden`), and its real
+  layer is a browser suite.
+- **`elementFromPoint` is the assertion**, not "the button has non-zero size":
+  `document.elementFromPoint(cx, cy).closest("#start")` must be the button. That
+  is the only in-browser statement that means *a finger or a cursor would hit it*,
+  and it is exactly the check that fails today.
+- Success criterion: the **entire** project test suite passes 100% (every test,
+  not just this phase's — pre-existing failures included) with **>90% coverage**
+  on new/modified code, and all four gates from `AGENTS.md` §4 are green:
+  `uv run ruff check . && uv run ruff format --check .` · `uv run pyright` ·
+  `uv run pytest` · `MIRROR_REALDISPLAY=1 uv run pytest -m realdisplay`.
+- `tests/test_app.py::TestClientScripts` guards must stay green: no new element
+  ids, and the only cross-page ids remain `net`, `notice`, `toast`.
+- No `ntfy` anywhere in this phase (it is outbound-only and cannot answer
+  questions).
+
+## Documentation & Consistency (mandatory)
+
+- Each task updates `README.md` wherever its own change is user-visible (here: a
+  narrow-screen/phone sharer).
+- The phase's final pass reviews `README.md` **in its entirety** against the
+  project as it will stand after this phase and fixes every inconsistency found,
+  **including pre-existing ones not caused by this phase** (stale ports, commands
+  that no longer exist, a described layout that no longer matches).
+- For `AGENTS.md` the final pass fixes **stale statements only** — a dead command,
+  a changed rule, an outdated fact — and **never adds or expands its content**.
+- `PLAN.md` is not edited by this phase. Nothing here needs a new anchor: it is
+  plain CSS in the locked hand-written-frontend stack (A9/A10). `svh`/`dvh` units
+  and `align-content: safe center` are standard CSS with no dependency; the final
+  pass confirms both on the Firefox kiosk target (Firefox 101+ / ESR) and keeps a
+  `vh` fallback where the value is load-bearing.
+
+## Completion Criteria
+
+- [ ] `#start` passes the `elementFromPoint` hit test and is fully inside both the
+      stage box and the viewport at 320×568, 360×640, 390×844, 430×932, 480×800,
+      700×900, 900×480, 1024×600, 1280×450, 1280×800 and 1920×1080.
+- [ ] `#stop` remains clickable at those sizes **while sharing** (unchanged
+      behaviour, asserted rather than assumed).
+- [ ] `.stage` places its children in one grid cell: `grep`/regex guard shows no
+      plain-flow `.placeholder` sibling of the video, and `overflow: hidden` is
+      paired with a min-height or a scroll escape.
+- [ ] Live video still fills the stage with rounded corners (no regression from
+      the single-cell change) and `#livetag` still sits top-left.
+- [ ] `README.md` is accurate and consistent with the whole project; `AGENTS.md`
+      contains no stale statements (verified in the final pass); the full test
+      suite is 100% passing.
+- [ ] No behavior change in phases 01–03: keyboard navigation, sharpness and
+      audio gates all still green.
diff --git a/.agents/phases/todo/04_reachable_share_cta/01_one_cell_stage.md b/.agents/phases/todo/04_reachable_share_cta/01_one_cell_stage.md
new file mode 100644
index 0000000..cee7f8c
--- /dev/null
+++ b/.agents/phases/todo/04_reachable_share_cta/01_one_cell_stage.md
@@ -0,0 +1,79 @@
+# Task 01 — One cell, so the placeholder overlays the video
+
+**Phase:** `04_reachable_share_cta` · **Source:** user request in chat — "the share button is cut off by the preview-stage"
+**Story:** n/a
+
+## Objective
+
+Make `#preview-stage` a single grid cell. Today its children stack into rows, the
+idle `<video>` reserves a ~150 px row (an empty `<video>` is intrinsically
+300×150) and the placeholder — with the Share button in it — starts at
+`stage.top + 151` at every viewport width and runs off the bottom into
+`overflow: hidden`.
+
+## Work
+
+1. `src/mirror/static/app.css` — in the `.stage` rule (~L232–241) keep
+   `position: relative`, `aspect-ratio`, `background`, `border`,
+   `border-radius`, `overflow: hidden` and `place-items: center`, and make the
+   cell explicit:
+
+   ```css
+   grid-template: 1fr / 1fr;   /* one cell, not one row per child */
+   ```
+
+2. `src/mirror/static/app.css` — immediately after it, put every child in that
+   cell:
+
+   ```css
+   .stage > * { grid-area: 1 / 1; }
+   ```
+
+   so `#preview`, `#placeholder` and `#livetag` overlap instead of stacking.
+   DOM order already paints the placeholder above the video; do not add `z-index`.
+3. `src/mirror/static/app.css` — leave `.livetag` as `position: absolute` (an
+   abspos child is out of flow, so `grid-area` is inert for it, and moving it into
+   the grid flow would be a visual change beyond this fix).
+4. `src/mirror/static/app.css` — leave `.stage video { width: 100%; height: 100%;
+   object-fit: contain; }` alone: inside one cell it now means what it always
+   claimed to, and `object-fit: contain` keeps live video letterboxed with the
+   rounded corners intact.
+5. `src/mirror/static/app.css` — add a comment at the rule stating the invariant
+   the next reader must not break: *the stage is one cell; a child added to
+   `#preview-stage` shares that cell and must never push another child out of
+   view.*
+6. Do **not** touch `share.js` (`renderIdle()`/`renderLive()` already toggle
+   `#placeholder.hidden` correctly) and do not touch `mirror.html`.
+
+ASSUMPTION: a single grid cell rather than `.placeholder { position: absolute;
+inset: 0 }`. Both fix the stacking; the cell keeps the placeholder in flow (so its
+height participates in layout, which task 02 needs for the floor/ceiling) and it
+also fixes `#livetag`'s siblings for free.
+ASSUMPTION: no change to the `.stage` border-radius or background — the corner
+clipping over live video is intentional and is what `overflow: hidden` is for.
+
+## Testing & Quality
+
+- Manual/instrumented check while working (Chromium, `channel="chromium"`, over
+  `http://127.0.0.1:<port>`): at 320×568 and 1280×800 record
+  `#placeholder`'s offset from `#preview-stage` — it must no longer be the
+  constant 151 px, and `#start`'s bottom must be inside the stage at 1280×800
+  and closer to inside at 320×568 (task 02 finishes the narrow case).
+- `uv run pytest tests/test_app.py` — the stylesheet and script guards stay
+  green; `[hidden] { display: none !important }` still beats the new
+  `grid-template` on `#placeholder` when it is hidden.
+- Screenshot pair (idle, 1280×800 and 390×844) attached to the commit or written
+  into the commit message, so the visual change is reviewable.
+- Coverage: **>90%** on new/modified code (CSS only; covered by the browser suite
+  in task 03 and the guard in task 04).
+
+## Completion Criteria
+
+- [ ] `.stage` declares a single explicit cell and `.stage > *` declares
+      `grid-area: 1 / 1`.
+- [ ] `#placeholder` is centred over the video box rather than sitting below a
+      150 px empty-video row (verified in the browser, both idle and live).
+- [ ] Live share still fills the stage, letterboxed, with rounded corners and
+      `#livetag` top-left — no visual regression.
+- [ ] `uv run pytest tests/test_app.py` green; `uv run ruff check . &&
+      uv run ruff format --check . && uv run pyright` clean.
diff --git a/.agents/phases/todo/04_reachable_share_cta/02_size_the_stage_for_real_viewports.md b/.agents/phases/todo/04_reachable_share_cta/02_size_the_stage_for_real_viewports.md
new file mode 100644
index 0000000..f67fe17
--- /dev/null
+++ b/.agents/phases/todo/04_reachable_share_cta/02_size_the_stage_for_real_viewports.md
@@ -0,0 +1,88 @@
+# Task 02 — Give the stage a floor, a ceiling, and an escape hatch
+
+**Phase:** `04_reachable_share_cta` · **Source:** user request in chat — "cut off … in narrower view widths"
+**Story:** n/a
+
+## Objective
+
+`aspect-ratio: 16 / 10` alone makes the stage 180 px tall at 320 px wide (the
+placeholder needs 240 px there) and 543 px tall in a 480 px-high window (the CTA
+ends up below the fold). Bound the box from both ends and make "content taller
+than the stage" impossible to trap.
+
+## Work
+
+1. `src/mirror/static/app.css` — add to `.stage`:
+
+   ```css
+   min-height: 264px;                    /* 240px of placeholder at 320px wide + slack */
+   max-height: min(70vh, 640px);          /* fallback for browsers without svh */
+   max-height: min(70svh, 640px);
+   ```
+
+   Keep `aspect-ratio: 16 / 10` — with a floor and a ceiling it becomes the
+   *preferred* shape rather than a hard derivation.
+2. `src/mirror/static/app.css` — escape hatch so nothing can ever be unreachable
+   again, whichever way the geometry falls:
+
+   ```css
+   .stage .placeholder { max-height: 100%; overflow: auto; }
+   ```
+
+   and centre the cell with `align-content: safe center` (or `place-content: safe
+   center`) on `.stage`, so overflowing content aligns to the start instead of
+   being clipped in half by both edges — the classic centred-overflow trap that
+   hid half the button here.
+3. `src/mirror/static/app.css` — at narrow widths stop asking for a wide-screen
+   shape at all: inside `@media (max-width: 900px)` (the existing single-column
+   breakpoint, ~L228) add `.stage { aspect-ratio: 4 / 3; }`, and
+   `@media (max-width: 480px) { .stage { aspect-ratio: auto; } }` so a phone gets
+   a stage as tall as its content rather than a letterbox with a button in the
+   clip. Keep `min-height` doing the real work in both cases.
+4. `src/mirror/static/app.css` — trim the placeholder's own padding on small
+   screens (`@media (max-width: 480px) { .stage .placeholder { padding: 16px; } }`)
+   to buy back the 16 px, and leave `.btn.big` (measured 168×52) untouched — it is
+   already a comfortable ≥44 px target.
+5. `src/mirror/static/app.css` — keep the whole diff inside the `/* share */`
+   block so it cannot collide with phase 01's focus rules or phase 03's audio
+   marks in the same file.
+
+ASSUMPTION: `min-height: 264px` from the measured 240 px of placeholder content at
+320 px wide, not from a round number. If a future copy change makes the idle
+placeholder taller, the `overflow: auto` + `safe center` pair keeps it reachable
+rather than clipped.
+ASSUMPTION: `max-height: min(70svh, 640px)` — the preview is a *preview*; on a
+1920×1080 desktop the aspect ratio alone wanted 964 px and pushed the Session
+panel off the screen. The live video letterboxes inside it (`object-fit: contain`),
+so nothing is lost but the crop is visible.
+ASSUMPTION: `svh` with a preceding `vh` declaration (silent fallback where `svh`
+is unsupported). The kiosk fleet is Firefox on Silverblue; both are supported
+there, and the fallback means the ceiling is never load-bearing on an old browser.
+ASSUMPTION: no `dvh`, because a mobile URL bar changing the stage height mid-share
+is worse than a slightly conservative ceiling.
+
+## Testing & Quality
+
+- Browser check at the measured failure points (320×568, 360×640, 390×844,
+  480×800, 900×480, 1280×450): `#start`'s rect must be inside both the stage rect
+  and the viewport rect. Record before/after numbers in the commit message — the
+  "before" column is in `00_phase.md`.
+- `uv run pytest tests/test_app.py::TestStylesheet` — `test_hidden_always_means_gone`
+  and `test_no_rule_reintroduces_a_conflicting_display_for_hidden` stay green with
+  the new `overflow`/`max-height` rules (reveal with opacity/overflow, never
+  re-`display` something `hidden`).
+- `uv run pytest -m e2e` — the existing share tests
+  (`test_the_idle_share_page_offers_only_a_start`,
+  `test_a_shared_window_reaches_a_viewer_as_moving_pixels`) unchanged.
+- Coverage: **>90%** on new/modified code.
+
+## Completion Criteria
+
+- [ ] `#start` is fully inside `#preview-stage` and inside the viewport at 320×568,
+      390×844 and 480×800 (the three clip cases), and fully above the fold at
+      900×480 and 1280×450 (the two fold cases).
+- [ ] `.stage` has both a `min-height` and a `max-height`, and the placeholder has
+      a scroll escape.
+- [ ] At 1920×1080 the Session panel is reachable without scrolling past a
+      964 px preview.
+- [ ] `uv run pytest tests/test_app.py -m "not e2e"` green; gates clean.
diff --git a/.agents/phases/todo/04_reachable_share_cta/03_reachable_cta_e2e.md b/.agents/phases/todo/04_reachable_share_cta/03_reachable_cta_e2e.md
new file mode 100644
index 0000000..19f6355
--- /dev/null
+++ b/.agents/phases/todo/04_reachable_share_cta/03_reachable_cta_e2e.md
@@ -0,0 +1,91 @@
+# Task 03 — Prove the CTA is clickable at every width, idle and live
+
+**Phase:** `04_reachable_share_cta` · **Source:** user request in chat — "I can't click it in narrower view widths"
+**Story:** n/a
+
+## Objective
+
+A browser suite that fails today and passes after tasks 01–02, and that would
+catch the same class of regression on any future `/mirror` layout change. The
+assertion is a hit test, not a size check.
+
+## Work
+
+1. `tests/e2e/test_share_layout.py` — new file, `pytestmark = pytest.mark.e2e`,
+   reusing the `base_url` / `browser` / `start_sharing` fixtures and helpers from
+   `tests/e2e/conftest.py` (`channel="chromium"`, the fake-media-stream args, and
+   the page-over-`http://127.0.0.1` rule — `mediaDevices` is undefined elsewhere
+   and the page would render the insecure-origin notice instead of the button).
+2. Parametrise the viewport sweep — exactly the shapes measured in
+   `00_phase.md`, so the two failure modes stay individually covered:
+
+   ```python
+   VIEWPORTS = [
+       (320, 568), (360, 640), (390, 844), (430, 932), (480, 800),   # the clip cases
+       (700, 900), (900, 700), (1024, 600), (1280, 800), (1920, 1080),
+       (900, 480), (1280, 450),                                       # the below-the-fold cases
+   ]
+   ```
+   One page per shape (`browser.new_page(viewport=...)`) or one page driven
+   through `set_viewport_size` — either is fine; reload after each resize.
+3. The probe (this is the code that reproduced the bug — keep it verbatim in the
+   test so the next reader can re-run the diagnosis):
+
+   ```js
+   () => {
+     const b = document.querySelector("#start");
+     const s = document.querySelector("#preview-stage").getBoundingClientRect();
+     const r = b.getBoundingClientRect();
+     const hit = document.elementFromPoint(r.x + r.width / 2, r.y + r.height / 2);
+     return {
+       disabled: b.disabled,
+       in_stage: r.bottom <= s.bottom + 1 && r.top >= s.top - 1,
+       in_viewport: r.bottom <= innerHeight && r.right <= innerWidth && r.top >= 0,
+       hit_is_button: !!hit && !!hit.closest("#start"),
+       hit: hit ? hit.id || hit.tagName : null,
+       no_h_scroll: document.documentElement.scrollWidth <= innerWidth,
+     };
+   }
+   ```
+
+   Assert all of `in_stage`, `in_viewport`, `hit_is_button`, `no_h_scroll`, and
+   `disabled is False` — a disabled button would make the hit test vacuous. On
+   failure the assertion message must include `hit`, which named the culprit
+   (`H2`, `LABEL`, `#name`, `#share-link`) during diagnosis.
+4. Live-state sweep in the same file: `start_sharing(page)`, then at
+   320×568, 390×844 and 1280×450 assert `#stop` passes the same hit test,
+   `#placeholder` is `hidden`, `#livetag` is visible and inside the stage rect,
+   and the viewer side is untouched (leave that to the existing media tests — this
+   is layout, not pixels).
+5. `tests/e2e/test_share_layout.py` — verify the test **fails before the fix**:
+   run it against the pre-phase CSS (e.g. `git stash` of tasks 01–02, or a
+   temporary revert) and paste the failing widths into the commit message. A
+   layout test that never failed is not believed.
+
+ASSUMPTION: the sweep uses `elementFromPoint` rather than `page.click("#start")`
+because clicking starts a real capture and each click would need teardown; the hit
+test is the same claim with no side effects. Task 03 step 4 still exercises a real
+`start_sharing()` once, so the interaction path is not untested.
+ASSUMPTION: 320 px is the floor of "realistic". Below that the page is expected to
+scroll, not to fit.
+ASSUMPTION: `+/- 1px` tolerance on the containment comparisons for sub-pixel
+layout at fractional device pixel ratios.
+
+## Testing & Quality
+
+- `uv run pytest -m e2e -k share_layout` — green after tasks 01–02, red before.
+- `uv run pytest -m e2e` — whole browser suite green, including
+  `tests/e2e/test_keyboard_wall.py` if phase 01 has landed by then.
+- `MIRROR_REALDISPLAY=1 uv run pytest -m realdisplay` unaffected (no capture
+  change), but run it once in the phase's final pass.
+- Coverage: **>90%** on new/modified code; this task is tests + nothing else.
+
+## Completion Criteria
+
+- [ ] `tests/e2e/test_share_layout.py` exists, is parametrised over the 12
+      viewports, and asserts the `elementFromPoint` hit test for `#start`.
+- [ ] The same file asserts `#stop` is clickable while a share is live at three
+      of those shapes.
+- [ ] The commit message records the pre-fix failure (which widths failed and what
+      `hit` reported).
+- [ ] `uv run pytest` fully green; gates clean.
diff --git a/.agents/phases/todo/04_reachable_share_cta/04_css_guard_and_docs.md b/.agents/phases/todo/04_reachable_share_cta/04_css_guard_and_docs.md
new file mode 100644
index 0000000..0bc1d3a
--- /dev/null
+++ b/.agents/phases/todo/04_reachable_share_cta/04_css_guard_and_docs.md
@@ -0,0 +1,76 @@
+# Task 04 — Keep the two-row grid from coming back, and fix the docs
+
+**Phase:** `04_reachable_share_cta` · **Source:** user request in chat — "the share button is cut off by the preview-stage"
+**Story:** n/a
+
+## Objective
+
+A static stylesheet guard that fails loudly if `.stage` regresses into a stack of
+rows or loses its floor, plus the phase's documentation pass.
+
+## Work
+
+1. `tests/test_app.py::TestStylesheet` — add a guard in the file's existing regex
+   style (see `test_hidden_always_means_gone`), something like
+   `test_the_share_stage_is_one_cell`:
+   * the `.stage { … }` rule contains `grid-template: 1fr / 1fr` (or an equivalent
+     explicit single cell) **and** a `.stage > *` rule with `grid-area: 1 / 1`;
+   * the reason goes in the docstring, because the test looks arbitrary: *the
+     stage's children overlap on purpose; in plain flow an idle `<video>` is
+     intrinsically 300×150 and pushes the Share button out of an
+     `overflow: hidden` box.*
+2. `tests/test_app.py::TestStylesheet` — add
+   `test_the_stage_has_a_floor_and_a_ceiling`: the `.stage` rule contains both
+   `min-height` and `max-height`, and any rule that combines `overflow: hidden`
+   with `aspect-ratio` has a `min-height` in the same block. This is the general
+   statement of the bug — an aspect-derived box with no floor is a clip.
+3. `tests/test_app.py::TestStylesheet::test_hidden_always_means_gone` — add
+   `.placeholder` to the list of components that set their own `display` and are
+   toggled with `hidden`, since tasks 01–02 give it `overflow`/`max-height` and it
+   is toggled by `renderIdle()`/`renderLive()`.
+4. `README.md` — add the sharer-facing line where the pages/quickstart are
+   described: `/mirror` works down to a 320 px-wide viewport, the preview keeps
+   its shape but never shrinks below the controls it holds. Keep it user-facing;
+   no CSS internals in the README.
+5. `README.md` **full consistency pass** (mandatory, phase-level): read the whole
+   file against the project as it stands after phases 01–04 and fix every
+   inconsistency, **including pre-existing ones this phase did not cause** — stale
+   ports or commands, a described layout that no longer matches, a
+   `MIRROR_MAX_BITRATE` default that phase 02 changes, keyboard behaviour phase 01
+   adds. Cite the file:line of each fix in the commit message.
+6. `AGENTS.md` — fix **stale statements only** (a dead command, a changed rule, an
+   outdated fact), never add or expand content. If nothing is stale, say so in the
+   commit message rather than inventing an edit.
+7. `.agents/PLAN.md` — not touched by this phase. If the pass finds a PLAN
+   statement contradicted by reality (e.g. §6's "default 12 Mbit/s"), report it in
+   the commit message and to the user; only they may amend it.
+
+ASSUMPTION: the guards assert the *structure* (`grid-template` + `grid-area`)
+rather than a pixel value, matching the existing stylesheet tests' approach —
+pixel assertions belong in `tests/e2e/test_share_layout.py`, where a real browser
+can answer them.
+ASSUMPTION: no new CSS custom property for the stage floor. One value, one place,
+and a variable would hide the number from the guard regexes.
+
+## Testing & Quality
+
+- `uv run pytest tests/test_app.py::TestStylesheet` — the new guards pass, and each
+  one fails when its CSS change is reverted (verify by hand; note it in the commit
+  message).
+- `uv run pytest -m "not e2e"` fast suite green, then the whole suite including
+  `-m e2e` and `-m realdisplay` in the final pass.
+- Coverage: **>90%** on new/modified code; the entire project suite is 100%
+  passing before this phase is called done (`AGENTS.md` §4).
+
+## Completion Criteria
+
+- [ ] Two new `TestStylesheet` guards exist, pass, and demonstrably fail when the
+      corresponding CSS is reverted.
+- [ ] `.placeholder` is in the `[hidden]` component list.
+- [ ] README states the narrow-screen behaviour and survives a full-file
+      consistency review with every finding fixed or explicitly reported.
+- [ ] `AGENTS.md` has no stale statements and no new narrative.
+- [ ] Full gate: `uv run ruff check . && uv run ruff format --check . && uv run
+      pyright && uv run pytest && MIRROR_REALDISPLAY=1 uv run pytest -m realdisplay`.
+- [ ] Committed per `AGENTS.md` §9: Conventional Commits, `--no-gpg-sign`,
+      `LLM-Generated: true` trailer.