toga-ai 1.0.605 → 1.0.607

package/knowledge/1.0/apps/tools/features/oneuptime-monitor-status-panel.md

@@ -1,5 +1,5 @@
 ---
-title: OneUptime Monitor Status Panel & Outage Alerting (tools /clickup/react)
+title: OneUptime Monitor Status Panel & Outage Alerting (tools /developer)
 framework: "1.0"
 repo: tools
 project: Tools
@@ -10,7 +10,9 @@ updated: 2026-08-18
 owners: [kyalamarthi, jcardinal]
 files:
   - tools/assets/clickup/sprint-dashboard.html
-  - tools/mvc/clickup/react/get.php
+  - tools/_/app/clickup/monitors.php
+  - tools/v2/monitors/status/index.php
+  - tools/mvc/developer/get.php
 related:
   - ./clickup-sprint-dashboard.md
   - ../architecture.md
@@ -20,273 +22,271 @@ related:
 
 ## Summary
 
-A live **operational monitor column** on the wall-display dashboard at `/clickup/react`. The
-page is a two-column split — the ClickUp sprint board at 80%, the monitor column filling the
-rest, each a bordered rounded card. The column shows an overall status pill, a **single solid
-status circle** carrying the whole system's state, a per-status legend (count + %), and a
-"Degraded and offline" card listing name / group / status / how long it has been in that state.
-
-The display is designed to be read **from across a room**: when a monitor changes to a bad state
-it **beeps, pops up and blinks**, and for as long as anything is still down the **screen edges
-hold a standing colour tint**.
-
-It reads the **OneUptime public status-page overview API** directly from the browser. This is
-the **read/consumer** side of OneUptime and is unrelated to the push-heartbeat monitors the
-worker tiers report *into* — see
+A live **operational monitor column** on the wall-display dashboard at `/developer` (the route
+was renamed from `/clickup/react` — the internal asset path `assets/clickup/sprint-dashboard.html`
+and the `App_Clickup_*` class names are deliberately unchanged). The page is a two-column split —
+the ClickUp sprint board at 75%, the monitor column filling the rest.
+
+The panel is **state-adaptive: calm when healthy, loud when broken.**
+
+- **Healthy** = one calm full-height green hero ("ALL SYSTEMS OPERATIONAL" + monitor count), a
+  soft glow on a dark panel — **not** a saturated fill. In the green state the hero is
+  **full-bleed flush** to the pane edges (no panel header, no inner padding, no hero border —
+  clipped by the pane's `overflow:hidden` + rounded corners).
+- **Bad** = a saturated DEGRADED (amber) / OUTAGE (red) band plus the affected-monitor list as
+  cards that **grow to share the column height** (min-height floor, scroll when many). Each
+  affected card puts its icon centered **above** the text, larger, with a role-colored full
+  border; monitor names **wrap** (they used to truncate on the TV). Non-green states keep the
+  panel header + padded card layout.
+- **Unknown** = a neutral grey "STATUS UNKNOWN — Monitor data unavailable" when there is no
+  usable data — this closes the old "0 monitors parsed looks like all-green" gap.
+
+The display is read **from across a room**: a monitor changing to a bad state **beeps, pops up
+and blinks**, and for as long as anything is down the **screen edges hold a standing colour
+tint**.
+
+The monitor data now comes from a **server-side, same-origin proxy** (`/v2/monitors/status/`,
+`App_Clickup_Monitors`) — the browser no longer POSTs cross-origin to OneUptime. This is the
+**read/consumer** side of OneUptime, unrelated to the push-heartbeat monitors the worker tiers
+report *into* — see
 [OneUptime push-metric monitors for 2.0 workers](../../../../2.0/apps/worker2/features/oneuptime-worker2-monitoring.md)
-and [OneUptime external uptime monitoring for 1.0 workers](../../worker/features/oneuptime-worker-uptime-monitoring.md)
-for that side. Those docs define what *creates* the statuses this panel renders.
+and [OneUptime external uptime monitoring for 1.0 workers](../../worker/features/oneuptime-worker-uptime-monitoring.md).
+Those docs define what *creates* the statuses this panel renders.
 
 ## How it works
 
 ### One document, not a nested iframe
 
-The panel is implemented as React components **in the same `sprint-dashboard.html` document**
-as the sprint board. It is deliberately **not** a nested iframe: `mvc/clickup/react/get.php`
-already iframes this page, so nesting a second frame would load a **second React runtime** and
-run a **duplicate ~250 KB poll**.
+The panel is implemented as React components **in the same `sprint-dashboard.html` document** as
+the sprint board (via CDN React, no build step). It is deliberately **not** a nested iframe:
+`mvc/developer/get.php` already iframes this page, so a second frame would load a second React
+runtime and a duplicate poll. The sprint board component is `SprintBoard`, wrapped by a
+`Dashboard` that owns the monitor poll and passes it down as props, so the status panel and the
+alert watcher share **one** fetch loop.
+
+Only the monitor fetch runs at `MONITOR_REFRESH_MS`; sprint data stays on the page's 5-minute
+`AUTO_REFRESH_MS`.
+
+### Data source — server-side proxy `/v2/monitors/status/` (`App_Clickup_Monitors`)
+
+The client `useMonitors` hook now does a **same-origin GET** to `/v2/monitors/status/` and
+unwraps `.data` from the api2 envelope — the SSO session cookie authenticates it like every other
+`/v2/*` call. The old cross-origin browser POST to `oneuptime.com`, the client-side
+`buildMonitorModel` / `monRole` / `monVal` parsers, and the hardcoded `MONITOR_STATUS_PAGE_ID`
+were **removed from the HTML**.
 
-The existing sprint board was left byte-for-byte unchanged — its component was renamed
-`SprintBoard` and a two-line `Dashboard` wrapper added around it plus the monitor column. The
-monitor poll is lifted into `Dashboard` and passed **down as props**, so the status panel and
-the alert watcher share **one** fetch loop rather than polling twice.
+`App_Clickup_Monitors::serve()` (`_/app/clickup/monitors.php`) mirrors `App_Clickup_Sprint`:
 
-Only the monitor fetch runs at `MONITOR_REFRESH_MS` (15s); sprint data stays on the page's
-existing 5-minute `AUTO_REFRESH_MS`. At 15s, outage detection (beep/popup/blink) reacts within
-~15s, and the ~250 KB cross-origin poll costs ~1 MB/min per open tab.
+- Same **SSO / persona JSON auth gate** (`App_Auth::isLoggedIn()` + persona check, JSON 401/403
+  on failure), same **api2 `{success, data, errors}` envelope**, uuid4 transaction id.
+- Server-side **curl POST** to the OneUptime public status-page overview API, reducing the
+  **~250 KB** upstream payload to a **~1 KB** model:
+  `{total, buckets, rows[{key, name, group, statusName, role, since-epoch-ms}], overallName,
+  overallRole}`.
+- Caches ~5s via **APCu**, so one upstream fetch is shared across all open display tabs and every
+  tab shows one consistent fresh snapshot.
+- Status-page ID is a server constant `DEFAULT_STATUS_PAGE_ID`, overridable via
+  `[oneuptime] status_page_id` in config (location only — no value recorded here).
 
-### Upstream contract — OneUptime public status-page overview API
+This eliminated the app's **only** cross-origin browser dependency and its CORS / edge-cache /
+mixed-context fragility (the direct browser poll was silently not re-polling), and cut traffic
+from ~1 MB/min per tab to ~1 KB per poll.
 
-Reusable for any future status display. Endpoint:
+### Upstream contract — OneUptime public status-page overview API (now consumed server-side)
+
+Reusable for any future status display; the parsing now lives in PHP, not the browser. Endpoint:
 
 ```
 POST https://oneuptime.com/status-page-api/overview/<statusPageId>
 body: {}
 ```
 
-- **It is a POST, not a GET**, and it returns **raw JSON** — **not** the api2
-  `{isSuccess, data, messages}` envelope used everywhere else in TOGA. The payload **is** the
-  data. Do not unwrap a `.data` that isn't there.
-- A **public** status page needs **no auth** and answers with `Access-Control-Allow-Origin: *`,
-  so the browser can call it cross-origin with **no proxy and no credentials**. This is the one
-  cross-origin call on a page whose every other fetch is same-origin `/v2/*`.
-- The response is **~250 KB**.
-- Values arrive as **typed envelopes** — `{_type: "ObjectID" | "DateTime" | "Color", value: …}`
-  — so read `.value`, never the object. Dates are ISO-8601 UTC with a trailing `Z`.
+- **It is a POST, not a GET**, and returns **raw JSON** — **not** the api2 envelope. The payload
+  **is** the data.
+- Values arrive as **typed envelopes** — `{_type: "ObjectID" | "DateTime" | "Color", value: …}` —
+  so read `.value`. Dates are ISO-8601 UTC (`Z`).
 - A monitor's **current** state is `statusPageResources[].monitor.currentMonitorStatusId`,
-  resolved against the `monitorStatuses[]` list.
-- In `monitorStatusTimelines[]`, the entry with **`endsAt: null`** is the **open** interval —
-  i.e. when the current state began. That is what drives "in this state for X".
-
-The status page ID is currently a hardcoded constant (`MONITOR_STATUS_PAGE_ID`) in the HTML;
-moving it to config is part of the recommended next step below. (Identifier location only — no
-value recorded here.)
-
-### Status bucketing is derived, never hardcoded
-
-Buckets are computed from the status list itself, not from a hardcoded set of status names:
-
-- `isOperationalState` → **good**
-- the **worst-priority non-operational** status → **offline / critical**
-- anything in between → **degraded**
-
-So a renamed status, or a newly added one, still lands in the right bucket without a code
-change.
-
-### The status circle — the colour is the message
-
-`MonitorCircle` is **one filled circle** whose colour is the whole system's state: green
-all-clear, amber if anything is degraded, red if anything is offline, **red winning when both**.
-It draws **nothing inside it** — no total, no label.
-
-That is deliberate, and it replaced a `MonitorDonut` (a segmented ring showing per-status
-proportions with the total in the centre) which was **deleted**. From across a room the colour is
-what carries; the legend directly beneath still gives the exact per-status counts, so no
-information is lost. The SVG keeps an `aria-label` listing the counts, so screen readers still
-get the numbers that came off the face of the circle.
-
-The circle's colour comes from the **same `standingRole()`** that drives the screen-edge tint, so
-the circle and the edges can never disagree about severity.
+  resolved against `monitorStatuses[]`; the open timeline interval (`endsAt: null`) is when the
+  current state began ("in this state for X").
+- **Discovery — the id-shape asymmetry.** In the overview payload a monitor status's own `_id` is
+  a **plain string**, but the resource's `currentMonitorStatusId` is a **typed envelope**
+  (`{_type:'ObjectID', value}`). Unwrap the resource id; the status `_id` is already plain. (This
+  corrected an earlier mis-diagnosis that the client parser was broken — it was fine; the point is
+  now moot since parsing is server-side.)
+
+Status bucketing is **derived, not hardcoded**: `isOperationalState` → good; worst-priority
+non-operational → offline/critical; anything between → degraded. A renamed or new status still
+buckets correctly.
+
+### Panel presentation — state-adaptive (supersedes the solid status circle)
+
+The old design (a solid `MonitorCircle`, a per-status legend with counts + percentages, and a
+redundant status pill) was **removed**, and the panel header renamed **"Monitor status" →
+"Status"**. The governing decision (developer's "Option 2"): **calm when healthy, loud when
+broken.**
+
+- **`healthy` now requires `total > 0 && rows.length === 0`.** A green hero can no longer show on
+  an empty/malformed response — that renders **Unknown** instead (see below).
+- **Green** — a single calm full-height green hero (soft glow, dark panel — not a saturated fill),
+  full-bleed flush to the pane edges (no header, no inner padding, no hero border; clipped by the
+  pane's `overflow:hidden` + rounded corners).
+- **Degraded / outage** — a saturated amber/red band + the affected-monitor cards, which grow to
+  share the column height (min-height floor, scroll when many). Icon centered above the text,
+  larger, role-colored full border, wrapping names. Each card uses a **dark, role-tinted
+  background with a soft radial glow** (amber for degraded, red for offline) rather than a
+  near-black fill, so a single card that grows to fill the column reads as amber/red — not a
+  black void — while the saturated icon + status text stay legible on the tint.
+
+**Tuned for a dark wall TV.** The incident-card tints were brightened for a dark display (glow
+~0.34–0.38, lifted base fills), and the green "operational" hero and grey "Unknown" panel were
+brightened to match. Card fonts + icon, and the green hero's check / title / subtitle, were
+enlarged for across-the-room readability.
+
+### Unknown state — closes the false-green gap
+
+An empty/malformed OneUptime response (`total === 0`) or a fetch error with **no prior good
+model** now renders a neutral grey **"STATUS UNKNOWN — Monitor data unavailable"**, never the
+green hero. The server proxy leaves `total: 0` as-is for the client to treat as Unknown. This is
+the durable fix for the previously-documented "0 monitors parsed = reassuring all-green" known
+issue: a total loss of visibility no longer clears a standing red screen to green, and the mass
+row drop-out is no longer mistaken for a full recovery.
 
 ### Alerting — edge-triggered events over a level-triggered state
 
-**The distinction to carry to any future alerting surface.** Two separate mechanisms, and mixing
-them up is the bug:
+Two separate mechanisms; mixing them up is the bug:
 
 | | Trigger | Drives | Why |
 |---|---|---|---|
-| **Event** | **Edge** — fires on the transition | beeps, popup, 5s blink | A level-triggered *event* re-alarms every 15s poll for a monitor that has been offline an hour, and the wall display becomes a siren nobody can silence. |
-| **State** | **Level** — follows current state | standing edge tint, status circle | An edge-triggered *state* would show a clean screen when you open the page during an existing outage. **The board must never look healthy while it isn't.** |
-
-**Event — `useMonitorAlerts`** compares each poll's non-operational rows against the previous
-poll's:
-
-- The **first successful poll is the baseline**, so opening the page mid-outage is **silent**
-  (the standing tint, being level-triggered, still shows immediately).
-- A state that simply persists never re-alarms.
-- A full recovery to operational is **visually silent** (no popup, no tint) but now plays a
-  distinct **recovery chime** — see the recovery event below.
-- It fires on **any change of non-operational state** — `r.role !== previous.get(r.key)`, where
-  the row set only ever holds non-operational monitors, so good→degraded, good→offline,
-  degraded→offline **and offline→degraded** all alert. An earlier version compared severity
-  numerically (`SEVERITY[new] > SEVERITY[old]`), which silently suppressed **offline → degraded**
-  because that is a severity *decrease*. That transition is news, so it is now announced and the
-  now-unused `SEVERITY` map was deleted.
-
-The event presentation, held for `ALERT_HOLD_MS` (5s):
-
-- **Sound** — Web Audio beeps, synthesised at runtime, so there is **no audio asset to ship**.
-  Each role's sound is defined in a single `ALERT_SOUND` table keyed by role, read by a
-  generalised `playBeeps(role)` (signature unchanged: role → bool). Each entry carries a beep
-  **count**, base **freq** (Hz), a per-beep **step** (Hz added to each successive beep — `0` =
-  flat, positive = a rising chime), duration/gap/volume, and a **wave** shape. Current tuned
-  values: **warning (degraded) = 3× square @ 720 Hz** (flat), **critical (offline) = 4× square
-  @ 410 Hz** (flat), **recovered = 3× square rising chime 620 → 800 → 980 Hz** (freq 620,
-  step 180). Distinct count, pitch and the rising vs. flat contour make each event
-  recognisable across a room without looking. The three sounds were tuned by ear in a
-  throwaway standalone "Monitor Sound Lab" browser page and the final numbers ported in — the
-  lab is not part of the repo.
-- **Popup** — a centre overlay naming each affected monitor. **Bad-state events only** —
-  recovery fires no popup.
-- **Blink** — the tint element gains `.is-blinking` for the 5s pulse, then the colour **holds**.
-  **Bad-state events only** — recovery fires no blink and no tint.
-
-**Recovery event — audio-only, by design.** `useMonitorAlerts` also computes `recovered` = keys
-that were non-operational in the previous poll and have **dropped out of `model.rows`** this poll,
-and calls `playBeeps('recovered')` (the rising chime) for them. It deliberately fires **no popup
-and no screen tint**: the level-triggered standing tint already clears itself when a row leaves
-the set, and a green "all clear" popup/flash would fight the "the board only shouts when something
-is wrong" design. So recovery is silent **visually** but audible. Two edge rules: the **first
-poll is still the baseline** (opening the page mid-outage does not chime), and if a bad-state
-change and a recovery land in the **same 15s poll the bad-state alert wins** that tick, avoiding
-overlapping sounds (simultaneous transitions are rare).
+| **Event** | **Edge** — on the transition | beeps, popup, blink | A level-triggered event re-alarms every poll for a monitor down an hour → an unsilenceable siren. |
+| **State** | **Level** — current state | standing edge tint | An edge-triggered state would show a clean screen when you open the page mid-outage. **The board must never look healthy while it isn't.** |
+
+**Alert hold — popup and blink both 15s.** `useMonitorAlerts` returns `{alert, blink}` on
+separate timers, but both now hold for **15000ms**: the centre popup (`ALERT_POPUP_MS`) and the
+screen-edge blink (`ALERT_BLINK_MS`) each stay up a full 15s so a fresh alert is readable and
+visible across the room. (`prefers-reduced-motion` still kills the fast edge pulse — see Gotchas.)
+Previously both shared one 5s `ALERT_HOLD_MS`.
+
+**Event — `useMonitorAlerts`** compares each poll's non-operational rows against the previous:
+
+- The **first successful poll is the baseline**, so opening the page mid-outage is silent (the
+  standing tint still shows immediately, being level-triggered).
+- Fires on **any change of non-operational state** (`r.role !== previous.get(r.key)`), so
+  good→degraded, good→offline, degraded→offline **and offline→degraded** all alert.
+- It remembers each monitor's **full previous-poll row** (key→row), so recovered monitors can be
+  named by the recovery dialog below.
+- **Sound** — Web Audio beeps synthesised at runtime (no audio asset). A per-role `ALERT_SOUND`
+  table (count / freq / per-beep `step` / duration / gap / volume / `wave`) read by
+  `playBeeps(role)`. Current tuning: warning 3× square @ 720 Hz (flat), critical 4× square @
+  410 Hz (flat), recovered 3× square rising chime 620 → 800 → 980 Hz (freq 620, step 180).
+- **Popup + blink** on **bad-state** events.
+
+**Recovery event — dialog + chime, but no edge flash.** Keys that were non-operational last poll
+and dropped out of `model.rows` this poll play the rising recovery chime **and** now show the
+**centre dialog for 15s**: a green, check-icon "N monitor(s) OPERATIONAL" / "Back to operational"
+that lists each recovered monitor as "Operational" (named from the remembered previous-poll rows).
+The recovery branch sets a `role:'good'` alert (`AlertOverlay` has an `alert.role === 'good'`
+variant) but deliberately calls **no `setBlink`** — recovery fires **no screen-edge flash/tint**,
+because a green all-clear must not strobe the room and the level-triggered standing tint already
+self-clears when a row leaves the set. First poll is still the baseline; if a bad-state change and
+a recovery land in the same poll, the bad-state alert wins that tick.
 
 **State — `standingRole(model)`** returns `critical` if any row is offline, else `warning` if any
-is degraded, else `null` (no tint). The tint element only renders while `standingRole` is
-non-null, so a full recovery clears it.
+is degraded, else `null`. The tint element renders only while `standingRole` is non-null, so full
+recovery clears it. The tint (worst-current) and the popup (the event) can legitimately differ:
+a degraded-event popup can sit on a red screen because something else is still offline — correct,
+not a bug.
 
-Note the two can legitimately show different colours at once: the tint always reflects
-**worst-current** state while the popup reflects **the event**, so a degraded-event popup can sit
-on a red screen because something else is still offline. That is correct, not a bug.
+### Two colour pairs: meaning vs. legibility
 
-Verified across full cycles (against the original 1-beep-720 / 2-beep-990 tuning; the current
-values are 3×720 / 4×410 / recovered 620→800→980): distinct sounds per event, silent on
-unchanged, recovery now chimes but stays visually silent, popup held 4982 ms and 4955 ms against
-the 5s spec; amber standing → red when offline
-joined (priority) → amber when offline cleared → no tint on full recovery, with the blink
-stopping after 5s and the colour held. Circle verified against the DOM: `#0ca30c` all-clear,
-`#fab219` degraded only, `#d03b3b` with 1 degraded + 1 offline, and `textNodesInSvg = 0`.
+`MON_COLOR` is the **validated status palette** and drives everything that **carries meaning**.
+`MON_COLOR_BRIGHT` (`good:#25d825, warning:#ffd633, critical:#ff4d4d`) is used **only** for the
+full-screen edge rim, where the only job is legibility from across a room. Do not let the bright
+pair leak into anything semantic.
 
-### Two colour pairs: meaning vs. legibility
+Both reach the overlay as CSS custom properties (`--alert-color`, `--alert-bright`). The rim is a
+three-layer `box-shadow` (solid hot rim + tight bright bloom + a deep haze that stays on the base
+hue so the dashboard stays readable), each bright layer written
+`var(--alert-bright, var(--alert-color))` so it degrades to the base colour.
+
+Standing and blinking differ in intensity **and tempo**, keeping "still broken" distinct from
+"something just changed":
+
+- `.alert-flash` (standing) — 12px rim, **slowly breathes** opacity 0→1→0 on a **4-second**
+  ease-in-out loop (`@keyframes alert-breathe`, 2s fade-in / 2s fade-out).
+- `.alert-flash.is-blinking` (event) — 20px rim, `opacity: 1`, plus the fast **0.7s** pulse. Its
+  compound selector (0,2,0) out-specifies the standing breathe (0,1,0).
 
-`MON_COLOR` is the **validated status palette** and drives everything that **carries meaning** —
-icons, legend, popup border, status text, and the status circle. `MON_COLOR_BRIGHT`
-(`good:#25d825, warning:#ffd633, critical:#ff4d4d`) is used **only** for the full-screen edge rim,
-where nothing depends on its exact value and the only job is legibility from across a room. Do
-not let the bright pair leak into anything semantic.
-
-Both reach the overlay as CSS custom properties — `--alert-color` and `--alert-bright`. The rim is
-a **three-layer `box-shadow`**: solid hot rim + tight bright bloom + a deep haze that deliberately
-stays on the **base** hue, so the dashboard underneath stays readable instead of washing out. Each
-bright layer is written `var(--alert-bright, var(--alert-color))` so it **degrades to the base
-colour** if the property never reaches the element.
-
-Standing and blinking differ in intensity **and in animation tempo**, which is what keeps
-"still broken" distinguishable from "something just changed":
-
-- `.alert-flash` (standing) — 12px rim, **slowly breathes** its opacity 0 → 1 → 0 on a
-  **4-second ease-in-out loop** (`@keyframes alert-breathe { 0%,100% { opacity: 0 } 50% {
-  opacity: 1 } }`, applied `animation: alert-breathe 4s ease-in-out infinite` — a 4s cycle =
-  2s fade-in / 2s fade-out). It may sit on screen for hours, so the gentle breathe draws a
-  distant eye without reading as urgent. The tempo was tuned with the developer.
-- `.alert-flash.is-blinking` (event) — 20px rim, `opacity: 1`, plus the fast **0.7s** pulse.
-  Its compound selector (0,2,0) out-specifies the standing breathe (0,1,0), so a just-changed
-  monitor shows the urgent fast blink, not the slow breathe.
-
-The base `.alert-flash { opacity: .85 }` is the **reduced-motion fallback**, not the animated
-default — see the `prefers-reduced-motion` gotcha. It is deliberately non-zero so a
-reduced-motion viewer never lands on a fully-invisible (opacity 0) glow.
+The base `.alert-flash { opacity: .85 }` is the **reduced-motion fallback**, deliberately non-zero
+so a reduced-motion viewer never lands on a fully-invisible glow.
 
 ## Gotchas
 
+- **Never call `curl_close()` in App_ code — the strict handler turns its PHP 8.5 deprecation into
+  a fatal (prod incident CV-2).** `App_Clickup_Monitors` originally called `curl_close($ch)`. On
+  the production Elastic Beanstalk PHP (8.5) `curl_close()` is **deprecated**, and the App_
+  framework's strict error handler promotes that `E_DEPRECATED` to a **fatal**, so
+  `/v2/monitors/status/` 500'd with an HTML error page (Sentry id CV-2). Fix: remove the call
+  entirely — `curl_close()` has been a **no-op since PHP 8.0** (the handle is a GC-freed
+  `CurlHandle`); use `unset($ch)` if you want to drop the reference. Same fatal-from-strict-handler
+  family as the E_ALL / `buildArrayOfRows`-by-ref gotcha. The endpoint's final catch was also
+  broadened from `catch (Exception)` to **`catch (\Throwable)`** so any catchable `Error` degrades
+  to the JSON "Status unknown" envelope instead of a 500 page.
+- **`crypto.randomUUID()` is undefined on a non-secure origin — it crashed React to a black
+  screen.** The page sets a per-request `transactionId` header using `crypto.randomUUID()`, which
+  exists **only in a secure context** (https, or http on `localhost`/`127.0.0.1`). Served over
+  plain HTTP by hostname / LAN IP (e.g. `http://tools/…`, "Not secure"), it is `undefined` and
+  throws **before React mounts** → a black screen. Fixed with a `transactionId()` helper:
+  `crypto.randomUUID` if present → else `crypto.getRandomValues` (a real v4) → else a non-crypto
+  id. **Reusable for any browser code that must run over a non-secure origin** — never call
+  `crypto.randomUUID`/`crypto.subtle` unguarded.
 - **The embedding iframe needs `allow="autoplay"` or the alert sound is silently blocked.**
-  Browser autoplay policy is scoped **per-iframe**. `mvc/clickup/react/get.php` embedded the
-  dashboard with `allow="fullscreen"`, so Web Audio inside the frame was policy-blocked and the
-  beeps would never have sounded in the Tools app — with no error. It is now
-  `allow="fullscreen; autoplay"`. Any future iframed page that makes sound needs the same.
+  Browser autoplay policy is scoped **per-iframe**. `mvc/developer/get.php` embeds the dashboard
+  with `allow="fullscreen; autoplay"`. Any future iframed page that makes sound needs the same.
 - **Permission is not enough — browsers still require one user gesture per session.** The page
-  unlocks the `AudioContext` on the first click/keypress, and if an alert fires while audio is
-  still blocked the popup **says so** rather than failing silently. On an **unattended wall
-  display nobody ever clicks**, so alerts stay visual-only. For kiosk use, launch Chrome with
+  unlocks the `AudioContext` on the first click/keypress; if an alert fires while audio is still
+  blocked the popup says so rather than failing silently. On an **unattended wall display nobody
+  clicks**, so alerts stay visual-only. For kiosk use launch Chrome with
   `--autoplay-policy=no-user-gesture-required`.
-- **The `prefers-reduced-motion` override needs the compound selector.** Blinking is a
-  vestibular risk, so the reduced-motion rule kills the animation and holds the colour steady.
-  Once the blink moved to `.alert-flash.is-blinking` (specificity 0,2,0), a reduced-motion rule
-  on `.alert-flash` alone (0,1,0) **could no longer override it** and the screen kept pulsing.
-  The rule must list both: `.alert-flash, .alert-flash.is-blinking { animation: none; }`. Any
-  future state/modifier CSS split has the same trap. Because it already names `.alert-flash`,
-  this same rule **also covers the new slow `alert-breathe` breathe** — a reduced-motion viewer
-  falls back to the static `opacity: .85` glow with **no separate rule needed**.
-- **A parse failure currently looks calmer than an outage** (known issue, not fixed). If the
-  OneUptime call returns HTTP 200 with a malformed or empty body, `buildMonitorModel` yields
-  total 0, empty buckets and empty rows. The status pill correctly degrades to "Unknown", but
-  the affected-list card still reads **"All 0 monitors are operational"**, and any
-  previously-degraded monitor silently disappears — and, worse now that recovery is audible,
-  the mass drop-out is **indistinguishable from a full recovery**, so the panel plays the happy
-  **recovery chime** for every vanished monitor on a parse failure. Since the standing
-  tint and the status circle are both driven by that same empty row set, a parse failure also
-  **clears a standing red screen back to green** — the most reassuring possible display of a
-  total loss of visibility. Recommended fix: treat "zero resources parsed" as an **error
-  state**, not a healthy one.
-
-## Recommended next step (advisory — not built)
-
-Replace the direct browser → OneUptime poll with a small **server-side proxy endpoint** in the
-Tools app (e.g. `/v2/monitors/status/`) that fetches upstream, reduces the payload to the
-summary, and caches ~5s. Rationale:
-
-- The browser currently pulls **~250 KB every 15s (~1 MB/min per open tab)** to display about
-  six numbers; a proxy makes it ~1 KB.
-- One upstream fetch is shared across **all** open displays instead of one per tab.
-- It removes the cross-origin dependency, and therefore the CORS/autoplay coupling above.
-- The status page ID moves into **config** instead of hardcoded HTML.
-- It gives a natural home for **server-side transition history**, which is what edge-triggered
-  alerting really wants (today the baseline resets every time a tab reloads).
+- **The `prefers-reduced-motion` override needs the compound selector.** Once the blink moved to
+  `.alert-flash.is-blinking` (0,2,0), a reduced-motion rule on `.alert-flash` alone (0,1,0) could
+  no longer override it. The rule must list both:
+  `.alert-flash, .alert-flash.is-blinking { animation: none; }`. Because it already names
+  `.alert-flash`, this same rule also covers the slow `alert-breathe` breathe.
 
 ## Change history
-- 2026-08-18 — Wall-display cadence tuning. The standing edge-tint breathe cycle changed from
-  5s to **4s** (`animation: alert-breathe 4s …` — 2s fade-in / 2s fade-out), and
-  `MONITOR_REFRESH_MS` changed from 5s to **15s**, so outage detection now reacts within ~15s
-  (was ~5s) and the ~250 KB cross-origin poll drops from ~3 MB/min to ~1 MB/min per open tab.
-  Also corrects prior doc drift: the breathe cycle had been documented as 7s but the code was
-  actually 5s. (jcardinal)
-- 2026-08-14 — Generalised alert-sound synthesis and added a **recovery chime**. The old
-  `BEEP_COUNT`/`BEEP_HZ`/`BEEP_MS`/`BEEP_GAP_MS`/`BEEP_VOLUME` constants and the square-wave-only
-  `playBeeps` were replaced by a single per-role `ALERT_SOUND` table (count / freq / per-beep
-  `step` / duration / gap / volume / `wave`) read by a generalised `playBeeps(role)` (signature
-  unchanged). Retuned to degraded 3×square@720, offline 4×square@410 (was degraded 1×@720,
-  offline 2×@990). Recovery — a monitor dropping out of the non-operational row set — now plays
-  a distinct rising chime (620→800→980, freq 620/step 180) and is **audio-only by design**: no
-  popup, no tint (the standing tint already self-clears; a green "all clear" flash would fight
-  the "only shouts when wrong" design). First poll stays the silent baseline; a bad-state change
-  and a recovery in the same tick let the bad-state alert win. Sounds were tuned by ear in a
-  throwaway standalone browser "Sound Lab" (not a repo file) and ported in. Corrects the prior
-  "recovery is silent" and old beep-count/pitch documentation. (jcardinal)
-- 2026-08-14 — The standing (level-triggered) edge tint now **slowly breathes** its opacity
-  0→1→0 on a 7s ease-in-out loop (`@keyframes alert-breathe`) instead of holding a static tint,
-  so a still-broken screen draws a distant eye. The fast 0.7s `.is-blinking` event pulse still
-  out-specifies it, keeping "just changed" (fast) distinct from "still broken" (slow breathe);
-  tempo tuned with the developer (0.5→0.92/10s too subtle, 0→1/10s too slow → 0→1/7s). The
-  existing `prefers-reduced-motion` compound-selector rule already covers the new animation, so
-  reduced-motion falls back to the deliberately non-zero static `opacity: .85` glow. (jcardinal)
-- 2026-08-14 — Built the monitor status column on `/clickup/react` (split layout, solid status
-  circle + legend + degraded/offline card) as components in the same document rather than a
-  nested iframe, sharing one 5s poll; documented the OneUptime public status-page overview API
-  contract (POST, raw JSON not the api2 envelope, CORS-open, typed `{_type,value}` envelopes,
-  `endsAt: null` = open interval) and derived status bucketing. Alerting splits **edge-triggered
-  events** (beeps / popup / 5s blink, now firing on any non-operational change incl.
-  offline → degraded) from a **level-triggered standing tint** driven by `standingRole()`, which
-  also colours the circle so the two can never disagree; added the `MON_COLOR_BRIGHT` rim-only
-  palette. Fixed the iframe `allow="fullscreen; autoplay"` autoplay block and recorded the
-  user-gesture/kiosk caveat, the `prefers-reduced-motion` specificity trap, the malformed-body
-  "all 0 monitors operational" gap, and the server-side-proxy recommendation. (kyalamarthi)
+- 2026-08-18 — **State-adaptive redesign + server-side proxy + Unknown state + /developer rename.**
+  Replaced the solid `MonitorCircle` / legend / percentages / status pill with a calm full-height
+  green hero (full-bleed flush in the green state) vs. a saturated amber/red band with growing,
+  wrapping affected-monitor cards on a dark, role-tinted radial-glow background (brightened for a
+  dark TV, larger type); renamed the panel header to **"Status"** and widened the monitor column
+  (sprint board 80%→75%). Added a neutral grey **Unknown** state (`healthy` now requires
+  `total > 0 && rows.length === 0`), closing the old "0 parsed = all-green" gap. Both the centre
+  popup (`ALERT_POPUP_MS`) and the screen-edge blink (`ALERT_BLINK_MS`) now hold **15s**
+  (`useMonitorAlerts` returns `{alert, blink}` on separate timers). **Recovery** now shows a green
+  check-icon dialog for 15s naming the recovered monitors (a `role:'good'` `AlertOverlay` variant,
+  driven by remembered previous-poll rows) in addition to the rising chime, but still fires **no
+  edge flash/tint**. Monitor data now comes from a **server-side same-origin proxy**
+  `/v2/monitors/status/` (`App_Clickup_Monitors`, APCu ~5s cache, ~250 KB→~1 KB, status-page ID in
+  config), removing the client's cross-origin OneUptime POST and its parsers; recorded the
+  OneUptime id-shape asymmetry (resource `currentMonitorStatusId` is a typed
+  `{_type:'ObjectID',value}` envelope, the status `_id` is plain). Fixed prod incident **CV-2**:
+  removed `curl_close()` (deprecated in PHP 8.5 → fatal under the App_ strict handler) and
+  broadened the endpoint catch to `\Throwable`. Route renamed `/clickup/react` → `/developer`.
+  Added the `crypto.randomUUID()` non-secure-origin black-screen gotcha. (jcardinal)
+- 2026-08-18 — Wall-display cadence tuning. Standing edge-tint breathe cycle 5s→**4s**;
+  `MONITOR_REFRESH_MS` 5s→**15s** (outage detection now reacts within ~15s). Corrected prior doc
+  drift (breathe had been documented as 7s but code was 5s). (jcardinal)
+- 2026-08-14 — Generalised alert-sound synthesis and added a **recovery chime** (per-role
+  `ALERT_SOUND` table, retuned degraded 3×720 / offline 4×410 / recovered rising 620→800→980);
+  recovery is audio-only by design (no popup/tint). First poll stays the silent baseline;
+  bad-state change wins over a same-tick recovery. (jcardinal)
+- 2026-08-14 — Standing edge tint slowly breathes opacity 0→1→0 (`@keyframes alert-breathe`);
+  fast 0.7s `.is-blinking` event pulse out-specifies it; reduced-motion falls back to static
+  `opacity: .85`. (jcardinal)
+- 2026-08-14 — Built the monitor status column (split layout, solid status circle + legend +
+  degraded/offline card) as components in the same document sharing one poll; documented the
+  OneUptime public status-page overview API contract and edge-vs-level alerting; added the
+  `MON_COLOR_BRIGHT` rim palette and the iframe autoplay / user-gesture / reduced-motion gotchas.
+  (kyalamarthi)
+</content>
+</invoke>

package/knowledge/2.0/apps/_underscore/INDEX.md

@@ -17,7 +17,7 @@
 | [_Component_*/_Model_* project-namespace registration (autoloader) & backslash-qualify traps](features/component-model-namespace-registration.md) | Every **project-local** `_Component_*` and `_Model_*` class in a 2.0 app **must declare the project namespace** at the top of the file: ```php namespace <NAMESP | _underscore/Loader.php, worker2/_.php, api2/_.php, worker2/Component/Forecast/Db/Db.php, worker2/Component/Forecast/SaleImport/SaleImport.php, worker2/Component/Api/Oneuptime/Oneuptime.php, api2/Component/Api/Netsuite/Netsuite.php, _underscore/Component/Api/Paypal/Paypal.php |
 | [_Config group access — the two-argument "optional" form does NOT rescue a missing GROUP](features/config-group-access.md) | `_Config::<group>('<property>')` reads a value out of the active `Config/<ENVIRONMENT>.ini`, and **it throws when the requested group is absent from the ini.** | _underscore/Config.php, _underscore/Component/Api/Paypal/Paypal.php, _underscore/Worker.php, api2/Config/beta.ini, api2/Config/sandbox-dev.ini |
 | [Re-pointing a DB alias mid-request (_Database::register park/restore)](features/database-alias-repointing.md) | `_Database` keys **all live per-database runtime state by the connection ALIAS** (`Client` / `_underscore::DB_CLIENT`, `ClientLogs`, `Archive`), **not** by the | _underscore/Database.php, _underscore/Query.php, api2/Component/Api/V2/V2.php, api2/Component/Api/CrossClient/CrossClient.php |
-| [2.0 Email Send Pipeline (queue + Send worker)](features/email-send-pipeline.md) | In 2.0, `_Email::send()` **does not transmit** — it queues the message. | _underscore/Email.php, _underscore/String.php, worker2/Worker/Infrastructure/Email/Send.php |
+| [2.0 Email Send Pipeline (queue + Send worker)](features/email-send-pipeline.md) | In 2.0, `_Email::send()` **does not transmit** — it queues the message. | _underscore/Email.php, _underscore/String.php, worker2/Worker/Infrastructure/Email/Send.php, _underscore/Model/Client/Logs/Email.php, _underscore/Model/Client/Logs/EmailAttachment.php |
 | [Client Email Template Sending](features/email-template-sending.md) | `_Model_Client_EmailTemplate` sends a stored, client-defined email template by UUID. | _underscore/Model/Client/EmailTemplate.php, _underscore/Model/Client/EmailTemplateOutgoingEmailAddress.php, _underscore/Email.php |
 | [Error Reporting — Issue/Event Capture, Fingerprinting & Aggregation](features/error-reporting-issue-event.md) | Platform-wide error reporting for TOGA 2.0, built on an **Issue / Event** aggregation model in the **shared Core Logs DB**. | _underscore/Error.php, _underscore/Database.php, _underscore/Exception/Business.php, api2/Controller/Index.php, worker2/Controller/Index.php, _underscore/Model/Core/Logs/Issue.php, _underscore/Model/Core/Logs/Event.php, _underscore/Model/Core/Logs/IssueFingerprint.php, _underscore/Model/Core/Logs/IssueClickupTask.php, _underscore/Model/Core/Logs/IssueEmailAddress.php, _underscore/Model/Core/Logs/IssueAreaOwner.php, dbchanges2/Logs/2026-07-30a - Error reporting Issues and Events.sql, dbchanges2/Logs/2026-08-01a - Rename tables to singular.sql, dbchanges2/Logs_Client/2026-08-01a - Drop Error table.sql, dbchanges2/Core/2026-07-30a - Error escalation cron job.sql |
 | [Record-Changed Event Publishing (_Event::publish to SQS)](features/event-publish-sqs.md) | `_Event::publish()` (in `_underscore/Event.php`) is the PHP side of the real-time event pipeline. | _underscore/Event.php |