Shell 1.11.0: alerts — a module flashes every dashboard listening on one of six channels #41

2026-10-05T17:06:34-04:00

michael commented

2026-10-05 17:06:34 -04:00

What

A module that sees something a tech must act on now — a timer overrun, a meter past its limit, timecode gone — raises an alert on one of six channels, and every dashboard listening to that channel flashes until it is over.

Dashboard: the menu bar (brought out for the duration if it was hidden) and a frame round the screen alternate between the level's two colours, with the alert's text bold across the bar and a boxed channel number. Low fades slowly, medium faster, critical snaps with no fade and floods the board behind the tiles too, in a muted cut that shows faintly through the tile panels without costing their content any contrast. Several at once: the most severe takes the bar, with a +1.
Layouts menu: a folded Alerts row with six numbered toggles. The channel list saves with the layout, local and named; the server keeps it in saved layouts.
Admin: a folded Alerts section near the bottom — two colour pickers per level, a swatch running each level's cadence, and a Test row that flashes any level on any channel for 8 s. Colours persist as alerts.colors in the data directory's proddash.json.
Server: the hub. One alert per channel (a new one replaces the last), timed out server-side (1–600 s, 15 by default, 0 = held until cleared), broadcast over the shell stream as alert / alert-clear / alerts-config; GET /api/alerts for a dashboard that opens or reconnects mid-alert; POST /api/alerts, DELETE /api/alerts/<n>. A module's alerts end when it stops.
Modules raise with shell.alert({ channel, level, text, duration }) / shell.clearAlert(n) from the server entry, or moduleApi.alert() / moduleApi.clearAlert() from a tile.

Docs and tooling

docs/ALERTS.md — the whole feature, operator side and HTTP API.
Module guide: a Raising alerts section (fields, and the rules: raise on the transition, make the channel and the on/off admin settings, it is not a status) plus the new moduleApi and shell entries.
tools/alert.js raises / clears / lists from the command line; tools/alerts.test.js drives the server end to end.

Design calls

POST /api/alerts is open to the network like saving a layout — an alert is only a flash on local screens.
Module content is never recoloured; the flash lives in shell chrome (and, for critical, the board and tile panels at 88 %).

Verified

node tools/alerts.test.js and node tools/layout-roundtrip.test.js pass.
In the browser: subscribe/unsubscribe, bar held open while hidden by its notch and released after, stacked alerts, unsubscribed channel ignored, reload mid-alert, admin colour save propagating live, admin test flash, critical board flood. Fullscreen not exercised (embedded browser refuses requestFullscreen); it shares the notch's menubar state.

🤖 Generated with Claude Code

## What A module that sees something a tech must act on *now* — a timer overrun, a meter past its limit, timecode gone — raises an **alert** on one of six channels, and every dashboard listening to that channel flashes until it is over. - **Dashboard**: the menu bar (brought out for the duration if it was hidden) and a frame round the screen alternate between the level's two colours, with the alert's text bold across the bar and a boxed channel number. **Low** fades slowly, **medium** faster, **critical** snaps with no fade and floods the board behind the tiles too, in a muted cut that shows faintly through the tile panels without costing their content any contrast. Several at once: the most severe takes the bar, with a `+1`. - **Layouts menu**: a folded **Alerts** row with six numbered toggles. The channel list saves with the layout, local and named; the server keeps it in saved layouts. - **Admin**: a folded **Alerts** section near the bottom — two colour pickers per level, a swatch running each level's cadence, and a Test row that flashes any level on any channel for 8 s. Colours persist as `alerts.colors` in the data directory's `proddash.json`. - **Server**: the hub. One alert per channel (a new one replaces the last), timed out server-side (1–600 s, 15 by default, `0` = held until cleared), broadcast over the shell stream as `alert` / `alert-clear` / `alerts-config`; `GET /api/alerts` for a dashboard that opens or reconnects mid-alert; `POST /api/alerts`, `DELETE /api/alerts/<n>`. A module's alerts end when it stops. - **Modules** raise with `shell.alert({ channel, level, text, duration })` / `shell.clearAlert(n)` from the server entry, or `moduleApi.alert()` / `moduleApi.clearAlert()` from a tile. ## Docs and tooling - `docs/ALERTS.md` — the whole feature, operator side and HTTP API. - Module guide: a **Raising alerts** section (fields, and the rules: raise on the transition, make the channel and the on/off admin settings, it is not a status) plus the new `moduleApi` and `shell` entries. - `tools/alert.js` raises / clears / lists from the command line; `tools/alerts.test.js` drives the server end to end. ## Design calls - `POST /api/alerts` is open to the network like saving a layout — an alert is only a flash on local screens. - Module content is never recoloured; the flash lives in shell chrome (and, for critical, the board and tile panels at 88 %). ## Verified - `node tools/alerts.test.js` and `node tools/layout-roundtrip.test.js` pass. - In the browser: subscribe/unsubscribe, bar held open while hidden by its notch and released after, stacked alerts, unsubscribed channel ignored, reload mid-alert, admin colour save propagating live, admin test flash, critical board flood. Fullscreen not exercised (embedded browser refuses `requestFullscreen`); it shares the notch's menubar state. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

michael added 1 commit 2026-10-05 17:06:35 -04:00

Shell 1.11.0: alerts — a module flashes every dashboard listening on one of six channels 5ca0a672fa

A module that sees something a tech must act on now (a timer overrun, a meter
past its limit, timecode gone) raises an alert on a channel, 1–6, and every
dashboard listening to that channel flashes: the menu bar — brought out for
the duration if it was hidden — and a frame round the screen alternate between
the level's two colours, with the alert's text bold across the bar. Low fades
slowly, medium faster, critical snaps with no fade and floods the board behind
the tiles too, in a muted cut that shows faintly through the tile panels
without costing their content any contrast.

Server: the hub. One alert per channel (a new one replaces the last), timed
out server-side (1–600 s, 15 by default, 0 = held until cleared), broadcast
over the shell stream as `alert` / `alert-clear`; GET /api/alerts for a
dashboard that opens or reconnects mid-alert; POST /api/alerts and
DELETE /api/alerts/<n>, open like a layout save. Modules raise from their
server entry with shell.alert() / shell.clearAlert() or from a tile with
moduleApi.alert() / moduleApi.clearAlert(); a module's alerts end when it
stops. Colours live as alerts.colors in the data directory's proddash.json.

Dashboard: the Layouts menu gains a folded Alerts row with six numbered
toggles; the channel list saves with the layout, local and named (the server
keeps it in a saved layout). Admin: a folded Alerts section with two colour
pickers per level, a swatch running each level's cadence, and a Test row.

Docs: docs/ALERTS.md (the feature), a "Raising alerts" section in the module
guide, README. Tools: tools/alert.js raises/clears/lists from the command
line; tools/alerts.test.js drives it all end to end.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

michael merged commit f9cd292693 into main

2026-10-05 17:06:55 -04:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: michael/ProdDash#41