Lightbox: pin and size to visible viewport when framed

The staff-report iframe is expanded to full content height (no nested
scrollbar), so a modal <dialog> centered in its viewport landed in the
middle of the whole document and sat off-screen unless the parent page
was scrolled there. Cross-origin means the iframe can't read the
parent's scroll position itself.

Tab.tpl now broadcasts the iframe's visible slice (webform-mw-viewport,
rAF-throttled on scroll/resize/load and after each height change), and
AttachmentLightbox pins to that slice and fills its height. Falls back
to a fixed box when no viewport message arrives (older extension), and
standalone mode keeps native centering at a taller 85vh.

Extension bumped to 0.3.1 (template change -> re-copy + cv flush on
prod). PRODUCTION_CUTOVER.md change log updated.

PRODUCTION_CUTOVER.md

@@ -164,16 +164,42 @@ fill out the form to that Organization.
 
 ## 5. Install the `webform-mw` Civi extension
 
-The extension adds an **Engagement Report** tab to Organization
-contact pages that embeds the staff report in an iframe.
+The extension does two jobs:
+
+- adds an **Engagement Report** tab to Organization contact pages that
+  embeds the staff report in an iframe; and
+- exposes the **file-upload proxy route** `civicrm/webform-mw/upload`
+  (handled by `CRM_WebformMw_Page_Upload`) that the app's `/api/upload`
+  POSTs binary files to. This route was **added in v0.3.0** — a CRM
+  running an older version has the report tab but every form file
+  upload returns **502 Bad Gateway** (the app can't reach the route, so
+  `/api/upload` fails closed). **Production must be on v0.3.0 or later.**
 
 1. Copy `WebForm-mw/civi-extension/webform-mw/` to the CRM's
    `[civicrm.extensionsDir]` (usually
    `<civi-root>/sites/default/ext/`). The directory must be named
-   exactly `webform-mw` (matches `<key>` in `info.xml`).
+   exactly `webform-mw` (matches `<key>` in `info.xml`). When
+   **upgrading** an already-installed extension, overwrite the existing
+   directory in place.
 
 2. `Administer → System Settings → Extensions → Add new → Refresh`,
-   then **Install** next to "WebForm-mw".
+   then **Install** next to "WebForm-mw" (first install) or run the
+   **Upgrade** action if one is offered. If neither, **Disable** then
+   **Enable** the extension.
+
+   **Then flush caches** — `cv flush`, or
+   **Administer → System Settings → Cleanup Caches**. New menu routes
+   (like `civicrm/webform-mw/upload`) are only registered after the
+   router is rebuilt; copying files without a flush leaves the upload
+   route 404ing and uploads 502ing.
+
+   Confirm the upload route resolves (a `400` means the route is live;
+   a `404`/login redirect means the flush didn't take):
+
+   ```bash
+   curl -s -X POST https://crm.fci.coop/civicrm/webform-mw/upload
+   # → {"error":"Missing file part"}   ✓ route exists
+   ```
 
 3. Configure — add to `civicrm.settings.php`:
 
@@ -276,6 +302,11 @@ Run these against the production deploy:
 5. Open the target Organization in CiviCRM → **Engagement Report**
    tab. The staff report should render the submission you just made.
 
+6. On the form, attach a file to any file field. It should upload
+   without error. A **502** here means the `webform-mw` extension on
+   this CRM is older than v0.3.0 (or the post-upgrade cache flush was
+   skipped) — see step 5.
+
 ---
 
 ## Change log
@@ -286,6 +317,21 @@ so the rationale survives.
 - **2026-06-08** — Documented the field-242 "Unknown" default issue
   after a production submission was stamped `Stage = "Unknown"`.
   Cleared via `CustomField.update`; see step 2.
+- **2026-06-18** — Extension bumped to **v0.3.1** (lightbox fix). The
+  staff-report iframe is expanded to full content height, so the
+  attachment lightbox (a modal inside the iframe) centered in the whole
+  document and sat off-screen unless the parent page was scrolled to the
+  middle. `Tab.tpl` now broadcasts the iframe's visible slice
+  (`webform-mw-viewport`) and the app pins/sizes the lightbox to it.
+  **Re-copy the extension to prod and `cv flush`** (template change) —
+  same procedure as step 5; no settings change.
+- **2026-06-16** — Step 5 now states the file-upload feature requires
+  extension **v0.3.0+** (the `civicrm/webform-mw/upload` proxy route)
+  and documents the upgrade-vs-first-install path plus the mandatory
+  cache flush. Surfaced when production uploads returned **502**: prod
+  Civi still had v0.1.0, which has the Engagement Report tab but not
+  the upload route, so `/api/upload` couldn't reach it and failed
+  closed. Added a post-deploy upload check as step 6 of section 8.
 - **2026-06-16** — Step 6 split off `CIVI_FRAME_ALLOWED_ORIGINS` as a
   separate env from `CIVI_BASE_URL`. Surfaced after the production
   cutover hit a `frame-ancestors` block: the app's CSP only listed the