diff --git a/CLAUDE.md b/CLAUDE.md
index 050aa24..5695be6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -774,4 +774,32 @@ Respects `prefers-reduced-motion`. z-index sits below the scanline overlay
---
+## 16. Web server variant (`web/`)
+
+A multi-user, browser-based deployment of the *same* tooling lives in
+`web/` — see `web/README.md`. It is **not a fork**: it reuses `src/*` and
+serves `renderer/app.js` + `renderer/app.css` verbatim, rewriting
+`renderer/index.html` on the fly to swap in a browser `window.api` shim
+(`web/public/api-web.js`) and a responsive overlay (`web/public/web.css`).
+
+Consequences for editing:
+
+- **The renderer is shared.** Changes to `renderer/*` and `src/*` flow to
+ both the Electron app and the web app automatically. Keep `app.js`
+ free of Electron/Node globals (it already only touches `window.api` +
+ DOM) so the shim stays sufficient.
+- **`window.api` is the contract.** If you add an IPC channel (see §10),
+ also add it to `web/server.js` (a route) **and** `web/public/api-web.js`
+ (the shim method) or the web app won't have it. Streaming channels use
+ NDJSON (progress lines + a `{__final:…}` line) instead of IPC events.
+- **Per-session isolation.** `web/server.js` keeps one `McmsClient` per
+ browser session (cookie `pfw_sid`), vs. the Electron app's single global
+ `client`. CSV writes become browser downloads; file dialogs become
+ `
+ const tappable = drillKey && count > 0;
+ const chevron = tappable ? '
› ' : '';
+ return `
${escapeHtml(title)}${detail ? `${escapeHtml(detail)} ` : ''}
- ${count}
+ ${count}${chevron}
`;
}
+// Scrollable list/menu popped from a clickable dashboard stat (e.g. the
+// list of ONUs with abnormal Rx). `items` is [{primary, secondary}].
+function showListModal(title, items) {
+ const overlay = document.createElement('div');
+ overlay.className = 'modal-overlay';
+ const list = items.length
+ ? `
${items.map((it) =>
+ `
${escapeHtml(it.primary)} ${
+ it.secondary ? `${escapeHtml(it.secondary)} ` : ''}
`).join('')}
`
+ : '
Nothing to show — all clear.
';
+ overlay.innerHTML = `
+
+
${escapeHtml(title)} (${items.length})
+ ${list}
+
Close
+
`;
+ document.body.appendChild(overlay);
+ const close = () => { document.removeEventListener('keydown', onKey, true); overlay.remove(); };
+ const onKey = (e) => { if (e.key === 'Escape') { e.preventDefault(); close(); } };
+ overlay.querySelector('.modal-ok').addEventListener('click', close);
+ overlay.addEventListener('mousedown', (e) => { if (e.target === overlay) close(); });
+ document.addEventListener('keydown', onKey, true);
+ overlay.querySelector('.modal-ok').focus();
+}
+
async function loadDashboard() {
const extra = $('#dash-extra').checked;
$('#dash-status').textContent = extra
@@ -1633,12 +1664,13 @@ function renderDashboard(d) {
Health
@@ -1675,13 +1707,34 @@ function renderDashboard(d) {
$('#dash-sections').innerHTML = sections.join('');
- // Drill-down: clicking an ONU-state row jumps to the ONU tab pre-filtered.
+ // Drill-down: ONU-state rows jump to the ONU tab pre-filtered; health
+ // rows pop a list of the offending devices (like the iOS app).
for (const row of $$('#dash-sections .dash-row.tappable')) {
row.addEventListener('click', () => {
- const status = row.dataset.status;
- $('#filter-status').value = optionExists('#filter-status', status) ? status : '';
- showView('#view-fleet');
- if (!state.fleet.length) loadFleet(); else applyFilters();
+ if (row.dataset.status !== undefined) {
+ const status = row.dataset.status;
+ $('#filter-status').value = optionExists('#filter-status', status) ? status : '';
+ showView('#view-fleet');
+ if (!state.fleet.length) loadFleet(); else applyFilters();
+ return;
+ }
+ const drill = row.dataset.drill;
+ if (drill === 'rx') {
+ showListModal('ONUs with abnormal Rx', (d.optical.abnormalRx || []).map((x) => ({
+ primary: x.name || x.onuId,
+ secondary: `${fmtDbm(x.rx)} dBm${x.name ? ' · ' + x.onuId : ''}`,
+ })));
+ } else if (drill === 'tx') {
+ showListModal('ONUs with abnormal Tx', (d.optical.abnormalTx || []).map((x) => ({
+ primary: x.name || x.onuId,
+ secondary: `${fmtDbm(x.tx)} dBm${x.name ? ' · ' + x.onuId : ''}`,
+ })));
+ } else if (drill === 'laser') {
+ showListModal('OLTs with laser off', (d.lasersOff || []).map((x) => ({
+ primary: x.name || x.oltId,
+ secondary: `${x.laser} · ${x.oltId}`,
+ })));
+ }
});
}
diff --git a/src/dashboard.js b/src/dashboard.js
new file mode 100644
index 0000000..9851c5b
--- /dev/null
+++ b/src/dashboard.js
@@ -0,0 +1,110 @@
+// Shared dashboard telemetry aggregation. Pure — no Electron, no HTTP — so
+// both the Electron main process (api:dashboardStats) and the web server
+// (/api/dashboardStats) compute identical numbers. Modeled on the PONGo
+// iOS app's DashboardViewModel.
+
+const { extractOnuHealth } = require('./mcms-api');
+
+function toNum(v) {
+ if (typeof v === 'number') return Number.isFinite(v) ? v : null;
+ if (typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v))) return Number(v);
+ return null;
+}
+
+// PONGo OpticalThreshold (dBm): Rx in-spec is -28..-10; Tx floor is 3.
+const RX_LOW = -28, RX_HIGH = -10, TX_LOW = 3;
+
+/**
+ * @param {object} args
+ * @param {object[]} args.olts OLT-STATE docs (listAllOltStates).
+ * @param {object[]|null} [args.onuStates] ONU-STATE docs for the heavy
+ * optical/FEC scan, or null/undefined to skip it (the light default).
+ * @param {number|null} [args.controllerCount]
+ */
+function summarizeDashboard({ olts = [], onuStates = null, controllerCount = null } = {}) {
+ const oltCount = olts.length;
+
+ // Registration map: onuId -> bucket (prefer a non-Registered bucket on
+ // duplicates — the interesting signal), matching api:listFleet.
+ const stateByOnu = new Map();
+ for (const olt of olts) {
+ const buckets = olt?.['ONU States'] || {};
+ for (const [bucket, ids] of Object.entries(buckets)) {
+ if (!Array.isArray(ids)) continue;
+ for (const id of ids) {
+ const existing = stateByOnu.get(id);
+ if (!existing || existing === 'Registered') stateByOnu.set(id, bucket);
+ }
+ }
+ }
+ const onuTotal = stateByOnu.size;
+ const stateCounts = {};
+ for (const s of stateByOnu.values()) stateCounts[s] = (stateCounts[s] || 0) + 1;
+ const onuCounts = Object.entries(stateCounts)
+ .map(([state, count]) => ({ state, count }))
+ .sort((a, b) => b.count - a.count);
+
+ // Aggregate traffic + laser state from OLT-STATE.
+ // OLT TX BW = downstream (OLT→ONU), RX BW = upstream (ONU→OLT).
+ let downBps = 0, upBps = 0, trafficSeen = false;
+ const lasersOff = [];
+ for (const olt of olts) {
+ const pon = olt?.STATS?.['OLT-PON'] || {};
+ const tx = toNum(pon['TX BW Ethernet Rate bps']);
+ const rx = toNum(pon['RX BW Ethernet Rate bps']);
+ if (tx !== null) { downBps += tx; trafficSeen = true; }
+ if (rx !== null) { upBps += rx; trafficSeen = true; }
+ const laser = olt?.OLT?.['Laser Shutdown'];
+ if (typeof laser === 'string' && laser.toLowerCase() !== 'laser on') {
+ lasersOff.push({ oltId: olt._id, name: olt?.OLT?.Name || '', laser });
+ }
+ }
+
+ // Opt-in heavy scan: every ONU-STATE for optical + FEC health. Keeps the
+ // actual offender lists so the dashboard can drill down without re-fetch.
+ let optical = {
+ available: false,
+ abnormalRx: [], abnormalRxCount: 0,
+ abnormalTx: [], abnormalTxCount: 0,
+ };
+ let fecCounts = null;
+ if (Array.isArray(onuStates)) {
+ const abnormalRx = [], abnormalTx = [];
+ let available = false;
+ fecCounts = { ok: 0, pre: 0, post: 0, buggy: 0, nodata: 0, error: 0 };
+ for (const st of onuStates) {
+ const health = extractOnuHealth(st);
+ if (fecCounts[health.flag] !== undefined) fecCounts[health.flag] += 1;
+ const o = health.optical || {};
+ const rx = typeof o.rx === 'number' ? o.rx : null;
+ const tx = typeof o.tx === 'number' ? o.tx : null;
+ const name = st?.ONU?.Name || '';
+ if (rx !== null) {
+ available = true;
+ if (rx < RX_LOW || rx > RX_HIGH) abnormalRx.push({ onuId: st._id, rx, name });
+ }
+ if (tx !== null) {
+ available = true;
+ if (tx < TX_LOW) abnormalTx.push({ onuId: st._id, tx, name });
+ }
+ }
+ optical = {
+ available,
+ abnormalRx, abnormalRxCount: abnormalRx.length,
+ abnormalTx, abnormalTxCount: abnormalTx.length,
+ };
+ }
+
+ return {
+ onuTotal, oltCount, controllerCount,
+ onuCounts,
+ traffic: trafficSeen ? { downBps, upBps } : null,
+ lasersOff,
+ optical,
+ fecCounts,
+ extraStats: Array.isArray(onuStates),
+ sampledAt: new Date().toISOString(),
+ };
+}
+
+module.exports = { summarizeDashboard };
diff --git a/web/README.md b/web/README.md
new file mode 100644
index 0000000..183b8ef
--- /dev/null
+++ b/web/README.md
@@ -0,0 +1,99 @@
+# PON Fleet — web server
+
+A multi-user, browser-based front end for the same tooling as the Electron
+**PON Fleet Upgrader** (Dashboard / ONU firmware upgrades / OLT PON
+flooding mode). Built to sit behind a TLS-terminating reverse proxy so
+several operators can use it at once, **each with their own MCMS login**.
+
+## How it relates to the Electron app
+
+It does **not** duplicate the app — it reuses it:
+
+- **Core logic** comes straight from `../src/` (`mcms-api.js`,
+ `bank-strategy.js`, `dashboard.js`). One source of truth for every MCMS
+ quirk.
+- **The UI is the same files.** The server serves `../renderer/app.js` and
+ `../renderer/app.css` as-is and rewrites `../renderer/index.html` on the
+ fly (adds a mobile viewport, swaps in the browser API shim + a small
+ responsive overlay). So the Electron app and the web app never drift.
+- The only web-specific code is `server.js`, `public/api-web.js` (a
+ `window.api` shim: Electron IPC → `fetch` + NDJSON streaming, Electron
+ file dialogs → browser file pickers, CSV-to-Downloads → Blob download),
+ and `public/web.css` (responsive overlay).
+
+Because of the `../` references this folder **must** live inside
+`pon-fleet-upgrader/` (it borrows the already-installed `tough-cookie` from
+`../node_modules`). No separate `npm install` is needed.
+
+## Run
+
+```bash
+cd pon-fleet-upgrader/web
+npm start # node server.js — listens on 127.0.0.1:8080
+npm run check # node --check on server.js + api-web.js
+```
+
+Then browse to . Each browser logs in with its own
+MCMS host + credentials; the server keeps a separate `McmsClient` (separate
+cookie jar) per session.
+
+### Configuration (env)
+
+| Var | Default | Meaning |
+|---|---|---|
+| `PORT` | `8080` | listen port |
+| `HOST` | `127.0.0.1` | bind address — keep on localhost behind a proxy |
+| `PFW_IDLE_MINUTES` | `30` | idle-session expiry (logs the MCMS session out) |
+| `PFW_SECURE_COOKIE` | off | force the `Secure` cookie flag (else inferred from `X-Forwarded-Proto: https`) |
+| `PFW_VERBOSE` | off | verbose MCMS request logging (very noisy with many users) |
+
+## Reverse proxy
+
+Terminate TLS at the proxy and forward to `127.0.0.1:8080`. **Disable
+response buffering** so the NDJSON progress streams (bulk delete, FEC
+pre-flight, flood change, …) arrive live.
+
+Caddy:
+
+```
+mcms-tools.example.net {
+ reverse_proxy 127.0.0.1:8080 {
+ flush_interval -1 # don't buffer streamed responses
+ }
+}
+```
+
+nginx:
+
+```nginx
+location / {
+ proxy_pass http://127.0.0.1:8080;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ proxy_buffering off; # stream NDJSON progress live
+ proxy_read_timeout 300s; # bulk ops can run a while
+}
+```
+
+## Security notes
+
+- The server holds each logged-in user's **live MCMS session cookie in
+ memory**. Run it behind HTTPS, keep `HOST=127.0.0.1`, and rely on the
+ idle timeout. The session cookie is `HttpOnly`, `SameSite=Lax`, and
+ `Secure` behind TLS.
+- "Accept self-signed TLS certificate" disables verification **to MCMS**
+ for that session only (same as the desktop app).
+- There's no app-level user directory — anyone who can reach the page and
+ has valid MCMS credentials can log in. Restrict network access at the
+ proxy (mTLS / SSO / IP allow-list) if you need more than MCMS auth.
+- Several operators running bulk operations at once multiply load on MCMS;
+ the page-size-100 / timeout mitigations from the main `CLAUDE.md` §5
+ still apply per session.
+
+## What differs from the desktop app
+
+- **CSV files download through the browser** instead of auto-saving to
+ `~/Downloads` (a server can't write to each user's machine). Same
+ filenames, same BOM/CRLF/quoted format.
+- Firmware `.bin` and plan-CSV selection use the browser file picker.
+- Everything else — views, filters, FEC logic, flood-mode rules, the
+ dashboard and its drill-downs — is the shared renderer code.
diff --git a/web/package.json b/web/package.json
new file mode 100644
index 0000000..b6182f0
--- /dev/null
+++ b/web/package.json
@@ -0,0 +1,12 @@
+{
+ "name": "pon-fleet-web",
+ "version": "0.1.0",
+ "private": true,
+ "description": "Multi-user, reverse-proxy-friendly web server for the PON fleet tools. Reuses ../src core and ../renderer UI; per-session MCMS credentials.",
+ "main": "server.js",
+ "scripts": {
+ "start": "node server.js",
+ "check": "node --check server.js && node --check public/api-web.js"
+ },
+ "license": "UNLICENSED"
+}
diff --git a/web/public/api-web.js b/web/public/api-web.js
new file mode 100644
index 0000000..2c77cfa
--- /dev/null
+++ b/web/public/api-web.js
@@ -0,0 +1,190 @@
+// Browser drop-in for the Electron preload's `window.api`. Same method
+// signatures and the same streaming-callback contract (onXProgress + an
+// awaitable trigger), implemented over fetch + NDJSON streaming. This lets
+// the shared renderer/app.js run unchanged in any browser.
+//
+// Differences absorbed here so the renderer doesn't have to care:
+// - Electron dialogs -> hidden