Resi Cues 1.0.3: a login without access to the venue stops signing in every poll

Every 401/403 was answered by signing in again on the spot. For a login that
works but may not list the account's venues (media@waters.church at North
Attleboro got 403 on /venues), that was a successful sign-in on every 1s poll
-- the pattern that had just got another Resi account locked.

- A refusal straight after signing in is a permission, not an expired
  session: it is held off like a failed login, with the message "This Resi
  login isn't allowed to see its venues (403) — ask a Resi admin for access".
  Only a session over a minute old is renewed.
- 429 on any request holds off too, not only on the login.
- The players cache-bust fallback no longer drops the parameter for good on a
  401/403/429, which are about the login rather than the parameter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -365,6 +365,22 @@ below. Nothing is installed without someone clicking.
   as `Label | Message` — add `| #channel` to bind one to a channel — and up
   to eight quick emojis).
   Tile settings: avatars, timestamps, names and channel notices.
+- **Resi Cues** — how long until the next Resi cue point, for a campus
+  running video from another site. The tile is one number, as large as it
+  will go: the countdown to the next cue, its name above it, and the playhead
+  and the cue just passed underneath. It also offers that countdown and the
+  playhead to the **Timers** module, so they can sit among the ProPresenter
+  timers instead of in a tile of their own.
+  Both the cue list and the decoder's position come from Resi's cloud rather
+  than the decoder — the decoder reports upstream and central.resi.io hands it
+  back — so nothing is installed at the decoder end. Resi republishes a
+  position only every few seconds and each reading is already stale, so the
+  playhead is estimated between readings rather than repeated; a countdown
+  built straight from Resi's number sits seconds behind and moves in lurches.
+  Admin config: Resi login and password, which decoder to follow (the list is
+  read from the account), and a folded **Timing** group for the poll
+  intervals and a position trim.
+  Tile settings: cue name, previous cue, playhead, cue list.
 - **Band Lineup** — the backstage stage board: everyone on stage in their mic
   slot with photo, name and mic/pack label, on one shared board that every
   screen sees the same way — whoever edits it changes it everywhere, over SSE.

modules/resi-cues/client.js

@@ -0,0 +1,138 @@
+/* Resi Cues — the tile.
+ *
+ * One number matters: how long until the next cue. It is drawn as large as the
+ * tile allows, with the cue's name above it, because on a wall the operator reads
+ * it from across the booth.
+ *
+ * The countdown ticks locally. The server sends the playhead with the instant it
+ * was true (`estMs` at `estAt`) and whether playback is running; this adds the
+ * elapsed time since. That is what keeps the digits moving every second while
+ * Resi itself only reports every few seconds, and it means a slow poll never
+ * shows as a stalled clock.
+ */
+
+const TICK_MS = 250; // redraw faster than a second so the digit turns on time
+
+export default function create({ root, moduleApi }) {
+  let stream = null;
+  let ticker = null;
+  let state = null;
+
+  const settings = () => moduleApi.instanceSettings;
+
+  function el(tag, className, text) {
+    const node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+  }
+
+  function hms(ms) {
+    const total = Math.max(0, Math.round(ms / 1000));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    const pad = (n) => String(n).padStart(2, '0');
+    return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${m}:${pad(s)}`;
+  }
+
+  /** Where the playhead is right now, extrapolated from the last server word. */
+  function playheadMs() {
+    if (!state || state.estMs === null || state.estMs === undefined) return null;
+    return state.estMs + (state.playing ? Date.now() - state.estAt : 0);
+  }
+
+  function render() {
+    root.textContent = '';
+    const set = settings();
+
+    if (!state || state.status === 'error') {
+      const box = el('div', 'resi-empty');
+      box.append(el('div', 'resi-empty-line', (state && state.message) || 'Not connected'));
+      root.append(box);
+      return;
+    }
+
+    const here = playheadMs();
+    const wrap = el('div', 'resi-wrap');
+
+    if (state.next) {
+      if (set.showCueName !== false) wrap.append(el('div', 'resi-label', 'NEXT'));
+      if (set.showCueName !== false) wrap.append(el('div', 'resi-cue', state.next.name || 'Next cue'));
+      const remaining = here === null ? null : state.next.ms - here;
+      const count = el('div', 'resi-count', remaining === null ? '—' : hms(remaining));
+      if (remaining !== null && remaining <= 30000) count.classList.add('is-soon');
+      if (!state.playing) count.classList.add('is-held');
+      wrap.append(count);
+    } else {
+      wrap.append(el('div', 'resi-label', state.event ? 'NO CUES LEFT' : 'NOTHING PLAYING'));
+      wrap.append(el('div', 'resi-cue', state.event || state.decoder || ''));
+    }
+
+    const foot = el('div', 'resi-foot');
+    if (set.showPrevious !== false && state.prev) {
+      foot.append(el('span', 'resi-foot-item',
+        `after ${state.prev.name}${here === null ? '' : ` · ${hms(here - state.prev.ms)} ago`}`));
+    }
+    if (set.showPosition !== false && here !== null) {
+      foot.append(el('span', 'resi-foot-item', `playhead ${hms(here)}`));
+    }
+    if (!state.playing && state.estMs !== null) foot.append(el('span', 'resi-foot-item is-held', 'paused'));
+    if (foot.childElementCount) wrap.append(foot);
+
+    if (set.showCueList && state.cues && state.cues.length) {
+      const list = el('ul', 'resi-list');
+      for (const cue of state.cues) {
+        const row = el('li', 'resi-list-row');
+        if (here !== null && cue.ms <= here) row.classList.add('is-past');
+        if (state.next && cue.ms === state.next.ms) row.classList.add('is-next');
+        row.append(el('span', 'resi-list-name', cue.name));
+        row.append(el('span', 'resi-list-at', hms(cue.ms)));
+        list.append(row);
+      }
+      wrap.append(list);
+    }
+
+    root.append(wrap);
+  }
+
+  function applyStatus() {
+    if (!state) return moduleApi.setStatus('connecting', 'Waiting for the server');
+    if (state.status !== 'ok') return moduleApi.setStatus('error', state.message || 'Not connected');
+    if (!state.playing) return moduleApi.setStatus('connecting', `Playback stopped — ${state.decoder}`);
+    const cadence = state.cadenceMs ? ` · Resi updates every ${Math.round(state.cadenceMs / 1000)}s` : '';
+    return moduleApi.setStatus('ok', `${state.decoder}${cadence}`);
+  }
+
+  return {
+    start() {
+      moduleApi.setStatus('connecting', 'Connecting');
+      stream = moduleApi.sse('/stream', {
+        state: (data) => {
+          try {
+            state = JSON.parse(data);
+          } catch {
+            return;
+          }
+          applyStatus();
+          render();
+        },
+        error: () => moduleApi.setStatus('error', 'Lost the connection to ProdDash'),
+      });
+      ticker = setInterval(render, TICK_MS);
+      render();
+    },
+
+    stop() {
+      if (stream) stream.close();
+      if (ticker) clearInterval(ticker);
+      stream = null;
+      ticker = null;
+      root.textContent = '';
+    },
+
+    onConfigChange() {
+      render();
+    },
+  };
+}

modules/resi-cues/module.json

@@ -0,0 +1,91 @@
+{
+  "id": "resi-cues",
+  "name": "Resi Cues",
+  "version": "1.0.3",
+  "proddash": ">=1.4.0",
+  "description": "Time until the next Resi cue point, on the board and as a timer",
+  "provides": ["timers"],
+  "client": "client.js",
+  "server": "server.js",
+  "style": "style.css",
+  "minSize": { "w": 2, "h": 1 },
+  "defaultSize": { "w": 4, "h": 3 },
+  "configGroups": {
+    "Resi account": {
+      "help": "The Resi Studio login the board reads with. Cue points and the decoder's playhead both come from Resi's cloud, so nothing is installed at the decoder. Worth using a dedicated low-privilege Resi user rather than a personal one."
+    },
+    "Decoder": {
+      "help": "Which decoder to follow. The list is read from the account once the login above is saved."
+    },
+    "Timing": {
+      "collapsed": true,
+      "help": "Resi refreshes a decoder's position only every few seconds, on an irregular cadence, and each reading is already slightly stale. The board estimates between readings rather than repeating them, so these only change how often it asks — not how accurate it is."
+    }
+  },
+  "configSchema": {
+    "username": {
+      "type": "string",
+      "label": "Resi login",
+      "group": "Resi account",
+      "default": "",
+      "help": "The email address used to sign in to studio.resi.io."
+    },
+    "password": {
+      "type": "password",
+      "label": "Password",
+      "group": "Resi account",
+      "default": ""
+    },
+    "player": {
+      "type": "select",
+      "label": "Decoder",
+      "group": "Decoder",
+      "default": "",
+      "optionsRoute": "/decoders",
+      "help": "Leave unset to follow the only decoder on the account."
+    },
+    "pollSeconds": {
+      "type": "number",
+      "label": "Position poll (s)",
+      "group": "Timing",
+      "default": 1,
+      "help": "How often Resi is asked where the playhead is. A faster poll notices a fired cue sooner; it does not make the countdown smoother, which is handled by estimating between readings."
+    },
+    "cueRefreshSeconds": {
+      "type": "number",
+      "label": "Cue list refresh (s)",
+      "group": "Timing",
+      "default": 5,
+      "help": "How often the cue list is re-read. It is also re-read immediately whenever the playhead jumps, so a cue fired at the host shows up without waiting for this."
+    },
+    "positionTrimMs": {
+      "type": "number",
+      "label": "Position trim (ms)",
+      "group": "Timing",
+      "default": 0,
+      "help": "Leave at zero. Only needed if the whole chain reads consistently behind; a positive value pushes the estimate forward."
+    }
+  },
+  "instanceSchema": {
+    "showCueName": {
+      "type": "switch",
+      "label": "Cue name",
+      "default": true
+    },
+    "showPrevious": {
+      "type": "switch",
+      "label": "Previous cue",
+      "default": true
+    },
+    "showPosition": {
+      "type": "switch",
+      "label": "Playhead",
+      "default": true
+    },
+    "showCueList": {
+      "type": "switch",
+      "label": "Cue list",
+      "default": false
+    }
+  }
+}

modules/resi-cues/resi.js

@@ -0,0 +1,338 @@
+/* Resi Cues — talking to Resi, and working out where the decoder actually is.
+ *
+ * Two things live here, both free of the shell so they can be tested on their own
+ * (`resi.test.js`): a thin client for the Resi Central API, and the playhead
+ * estimator that turns its coarse, late readings into a usable position.
+ *
+ * The API is the undocumented one behind studio.resi.io. It is not supported by
+ * Resi and can change without notice; that is the price of there being no public
+ * way to read cue points at all.
+ */
+
+'use strict';
+
+const RESI = 'https://central.resi.io';
+
+/* ── time ──────────────────────────────────────────────────────────────── */
+
+/** '01:02:03.500' → milliseconds, or null when it is not a position at all. */
+function positionToMs(position) {
+  if (typeof position !== 'string') return null;
+  const parts = position.split(':');
+  if (parts.length !== 3) return null;
+  const hh = Number(parts[0]);
+  const mm = Number(parts[1]);
+  const ss = Number(parts[2]);
+  if (!Number.isFinite(hh) || !Number.isFinite(mm) || !Number.isFinite(ss)) return null;
+  return Math.round((hh * 3600 + mm * 60 + ss) * 1000);
+}
+
+/** milliseconds → 'HH:MM:SS.mmm', the shape Resi's own cue positions use. */
+function msToPosition(total) {
+  const t = Math.max(0, Math.floor(total));
+  const pad = (n, w) => String(n).padStart(w, '0');
+  return `${pad(Math.floor(t / 3600000), 2)}:${pad(Math.floor((t % 3600000) / 60000), 2)}`
+    + `:${pad(Math.floor((t % 60000) / 1000), 2)}.${pad(t % 1000, 3)}`;
+}
+
+/* ── the playhead estimator ────────────────────────────────────────────── */
+
+const WINDOW_MS = 120000;   // how long a reading stays useful
+const JUMP_FLOOR_MS = 5000; // the smallest move ever treated as a seek
+const LOGIN_BACKOFF_MS = 15000;      // first wait after a failed Resi login
+const LOGIN_BACKOFF_MAX_MS = 300000; // longest wait between login attempts
+const SESSION_FRESH_MS = 60000;      // a refusal younger than this is a permission, not an expired session
+
+/**
+ * Resi republishes a decoder's `position` only every few seconds, on an irregular
+ * cadence, and each reading is already a little stale when it appears. Shown raw,
+ * a countdown built on it sits seconds behind and moves in lurches.
+ *
+ * So every reading is kept as *media time minus wall time*. While playback runs at
+ * 1x that difference is constant, and the LARGEST recent value is the reading that
+ * reached us with the least delay — the one to trust. The estimate is then simply
+ * "now plus that offset", which advances smoothly by itself and cannot be dragged
+ * backwards by a slow round trip.
+ *
+ * `now` is injected so the tests can drive a fake clock.
+ */
+function createPlayhead(options) {
+  const opts = options || {};
+  const trimMs = Number(opts.trimMs) || 0;
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now();
+
+  let offsets = [];      // { at, off } — off is mediaMs - wall time it was read
+  let spreads = [];      // how far apart honest readings sit: this link's noise
+  let gaps = [];         // how long between the playhead actually moving
+  let changes = 0;       // readings that differed from the one before
+  let rejected = false;  // the last gap looked like a pause and was skipped
+  let base;              // the trusted offset
+  let lastMedia;
+  let lastNewAt;
+  let lastEst;
+  let seeked = false;
+
+  function note(mediaMs) {
+    if (!Number.isFinite(mediaMs)) return;
+    const t = now();
+    if (mediaMs !== lastMedia) {
+      const off = mediaMs - t;
+      // Anything inside the measured noise floor is noise; only a move clearly
+      // beyond it is a real seek. Measured rather than assumed, and remembered
+      // across a reset so the first reading after one is not judged blind.
+      const noise = spreads.length ? Math.max.apply(null, spreads) : 0;
+      const threshold = Math.max(JUMP_FLOOR_MS, noise * 1.5 + 4000);
+      if (base !== undefined) {
+        const delta = off - base;
+        if (Math.abs(delta) > threshold) {
+          offsets = [];               // the window describes where we used to be
+          seeked = true;
+          // Only abandon the no-going-backwards guard for a move big enough that
+          // snapping is obviously right; a marginal call must not make the
+          // displayed playhead lurch backwards.
+          if (Math.abs(delta) > 10000) lastEst = undefined;
+        } else if (delta < 0) {
+          spreads = spreads.concat(-delta).slice(-20);
+        }
+      }
+      // The first reading lands at an arbitrary point in Resi's cycle, so the gap
+      // from it to the next one is only a fraction of the real cadence. Learning
+      // from it locked in a 2s cadence that rejected every honest 30s gap.
+      if (lastNewAt !== undefined && changes > 0) {
+        const gap = t - lastNewAt;
+        // The gap either side of a pause is not Resi's cadence — recording it
+        // would inflate the estimate and make the next pause slow to notice.
+        // But a pause is one gap; twice in a row is the cadence having changed.
+        const worst = gaps.length ? Math.max.apply(null, gaps) : 0;
+        if (gap > 0 && gap < 60000) {
+          if (!worst || gap <= worst * 3 || rejected) {
+            gaps = gaps.concat(gap).slice(-8);
+            rejected = false;
+          } else {
+            rejected = true;
+          }
+        }
+      }
+      if (lastNewAt !== undefined) changes++;
+      offsets = offsets.concat({ at: t, off });
+      lastMedia = mediaMs;
+      lastNewAt = t;
+    }
+    const kept = offsets.filter((o) => t - o.at <= WINDOW_MS);
+    // Always keep the newest reading even once it ages out. If the window empties
+    // during a long pause there is nothing left to compare against, and the resume
+    // reads as an ordinary reading instead of the discontinuity it is.
+    offsets = kept.length ? kept : offsets.slice(-1);
+    base = offsets.length ? offsets.reduce((m, o) => (o.off > m ? o.off : m), -Infinity) : undefined;
+  }
+
+  function read() {
+    if (lastNewAt === undefined) return { estMs: null, playing: false, cadenceMs: 0 };
+    const t = now();
+    const cadenceMs = gaps.length ? Math.max.apply(null, gaps) : 0;
+    // Only call it paused once the playhead has been still for clearly longer than
+    // Resi's own cadence. A fixed timeout mistakes a slow update for a stop, and a
+    // countdown that freezes mid-service is the worse failure of the two.
+    // Until a full gap has been measured the cadence is unknown; assume the slowest
+    // Resi plausibly is, or a 30s publisher reads as paused 15s after every start.
+    const pauseAfter = cadenceMs ? Math.max(15000, Math.min(45000, cadenceMs * 2.5 + 6000)) : 45000;
+    const playing = base !== undefined && t - lastNewAt < pauseAfter;
+    if (!playing) {
+      return { estMs: lastEst !== undefined ? lastEst : lastMedia, playing: false, cadenceMs };
+    }
+    let est = t + base + trimMs;
+    if (lastEst !== undefined && est < lastEst) est = lastEst; // the base is a max
+    lastEst = est;
+    return { estMs: est, playing: true, cadenceMs };
+  }
+
+  /** True once per detected discontinuity — the caller re-reads the cue list. */
+  function takeSeek() {
+    const was = seeked;
+    seeked = false;
+    return was;
+  }
+
+  return { note, read, takeSeek };
+}
+
+/* ── the Resi Central API ──────────────────────────────────────────────── */
+
+/**
+ * Login sets a `livingas1` cookie which doubles as the bearer token, sent as
+ * `Authorization: X-Bearer <cookie>`. Everything else is a plain GET.
+ */
+function createResiClient(options) {
+  const opts = options || {};
+  const doFetch = opts.fetch || globalThis.fetch;
+  let cookieHeader = '';
+  let token = '';
+  let loggedInAt = 0;
+  let customerId = '';
+  let cacheBust = true;
+
+  function headers() {
+    const h = { Accept: 'application/json' };
+    if (cookieHeader) h.Cookie = cookieHeader;
+    if (token) h.Authorization = `X-Bearer ${token}`;
+    return h;
+  }
+
+  /* A failed login used to be retried on the very next poll -- once a second, for
+     ever. Resi answers that with 429s, and since the retries never let up, the
+     account never got out of them. So a failure now holds off further attempts,
+     doubling from 15s to 5min (or as long as Resi's Retry-After asks), and every
+     call in between fails at once with the same reason instead of signing in. */
+  const now = typeof opts.now === 'function' ? opts.now : () => Date.now();
+  let loginFailures = 0;
+  let loginBlockedUntil = 0;
+  let loginError = '';
+
+  async function login() {
+    if (now() < loginBlockedUntil) {
+      const wait = Math.ceil((loginBlockedUntil - now()) / 1000);
+      throw new Error(`${loginError} — retrying in ${wait}s`);
+    }
+    let res;
+    try {
+      res = await doFetch(`${RESI}/api/v3/login?newToken=true`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify({ userName: opts.username, password: opts.password }),
+      });
+    } catch (err) {
+      holdOff(`Resi unreachable (${(err && err.message) || err})`, 0);
+      throw new Error(loginError);
+    }
+    if (!res.ok) {
+      const reason = res.status === 429 ? 'Resi is rate-limiting this login (429)'
+        : res.status === 400 || res.status === 401 ? `Resi rejected the login (${res.status}) — check the password`
+          : `Resi login failed (${res.status})`;
+      const retryAfter = Number(res.headers && res.headers.get && res.headers.get('retry-after')) || 0;
+      holdOff(reason, retryAfter * 1000);
+      throw new Error(reason);
+    }
+    loginFailures = 0;
+    loginBlockedUntil = 0;
+    loginError = '';
+    const setCookies = (res.headers.getSetCookie && res.headers.getSetCookie())
+      || (res.headers.get('set-cookie') ? [res.headers.get('set-cookie')] : []);
+    const jar = {};
+    for (const raw of setCookies) {
+      const first = String(raw).split(';')[0];
+      const eq = first.indexOf('=');
+      if (eq > 0) jar[first.slice(0, eq)] = first.slice(eq + 1);
+    }
+    token = jar.livingas1 || '';
+    if (!token) throw new Error('Resi login returned no session cookie');
+    cookieHeader = Object.keys(jar).map((k) => `${k}=${jar[k]}`).join('; ');
+    loggedInAt = now();
+    const me = await get('/api_v2.svc/users/me');
+    customerId = (me && me.customerId) || '';
+    if (!customerId) throw new Error('This Resi account has no customerId');
+    return me;
+  }
+
+  function holdOff(reason, askedMs) {
+    loginFailures++;
+    const backoff = Math.min(LOGIN_BACKOFF_MAX_MS, LOGIN_BACKOFF_MS * 2 ** (loginFailures - 1));
+    loginBlockedUntil = now() + Math.max(backoff, askedMs || 0);
+    loginError = reason;
+  }
+
+  async function ensureSession() {
+    if (!token || now() - loggedInAt > 50 * 60 * 1000) await login();
+  }
+
+  /* The same hold-off covers every request, not just the login. A 401/403 used to
+     sign in again on the spot, every time: for a login that simply isn't allowed to
+     see a venue, that was a fresh sign-in on every poll. Now a refusal straight
+     after signing in is taken as what it is -- a permission -- and held off like a
+     failed login; only an older session is renewed. A 429 holds off too. */
+  async function get(path) {
+    if (now() < loginBlockedUntil) {
+      const wait = Math.ceil((loginBlockedUntil - now()) / 1000);
+      throw new Error(`${loginError} — retrying in ${wait}s`);
+    }
+    let res = await doFetch(RESI + path, { method: 'GET', headers: headers() });
+    if ((res.status === 401 || res.status === 403) && now() - loggedInAt > SESSION_FRESH_MS) {
+      await login();
+      res = await doFetch(RESI + path, { method: 'GET', headers: headers() });
+    }
+    if (res.status === 401 || res.status === 403) {
+      const where = path.includes('/venues') ? 'its venues'
+        : path.includes('/players') ? "this venue's decoders" : 'part of the account';
+      holdOff(`This Resi login isn't allowed to see ${where} (${res.status}) — ask a Resi admin for access`, 0);
+      throw new Error(loginError);
+    }
+    if (res.status === 429) {
+      const retryAfter = Number(res.headers && res.headers.get && res.headers.get('retry-after')) || 0;
+      holdOff('Resi is rate-limiting requests (429)', retryAfter * 1000);
+      throw new Error(loginError);
+    }
+    if (!res.ok) throw new Error(`Resi ${path} failed (${res.status})`);
+    return res.json();
+  }
+
+  async function venues() {
+    await ensureSession();
+    return (await get(`/api/v3/customers/${customerId}/venues`)) || [];
+  }
+
+  /** A stale cached reading looks exactly like a laggy playhead, so ask for a fresh
+   *  one — and if the service objects to the parameter, stop sending it. */
+  async function players(venueUuid) {
+    await ensureSession();
+    const path = `/api_v2.svc/users/${venueUuid}/players`;
+    if (cacheBust) {
+      try {
+        return (await get(`${path}?_=${Date.now()}`)) || [];
+      } catch (err) {
+        // Only an objection to the parameter itself; a refusal or a "slow down"
+        // (401/403/429) is about the login, and dropping it then lost fresh readings.
+        const code = (String(err.message).match(/\((4\d\d)\)/) || [])[1];
+        if (!code || ['401', '403', '429'].includes(code)) throw err;
+        cacheBust = false;
+      }
+    }
+    return (await get(path)) || [];
+  }
+
+  async function event(eventId) {
+    await ensureSession();
+    return get(`/api/v3/customers/${customerId}/events/${eventId}`);
+  }
+
+  async function cues(profileId, eventId) {
+    await ensureSession();
+    const raw = (await get(
+      `/api_v2.svc/streamprofiles/${profileId}/events/${eventId}/cues?canISetCues=1`)) || [];
+    return raw
+      .map((c) => ({ name: String(c.name || ''), ms: positionToMs(c.position) }))
+      .filter((c) => c.ms !== null)
+      .sort((a, b) => a.ms - b.ms);
+  }
+
+  return {
+    login,
+    ensureSession,
+    venues,
+    players,
+    event,
+    cues,
+    get customerId() { return customerId; },
+  };
+}
+
+/** The cue after `estMs`, and the one before it. */
+function surroundingCues(cues, estMs) {
+  let prev = null;
+  let next = null;
+  for (const c of cues || []) {
+    if (c.ms > estMs) { next = c; break; }
+    prev = c;
+  }
+  return { prev, next };
+}
+
+module.exports = { positionToMs, msToPosition, createPlayhead, createResiClient, surroundingCues, RESI };

modules/resi-cues/resi.test.js

@@ -0,0 +1,236 @@
+'use strict';
+
+/**
+ * Unit tests for the Resi playhead estimator.
+ *
+ *   node modules/resi-cues/resi.test.js
+ *   node modules/resi-cues/resi.test.js 7000 1000 4000 2000   # one profile
+ *
+ * Plain Node, no dependencies; exits non-zero on the first failure.
+ *
+ * The estimator's whole job is to be right about a feed that is coarse, late and
+ * irregular, so the fixture is a simulated Resi rather than a list of values: a
+ * decoder playing at 1x, and an API that republishes its position every so often,
+ * already stale, over a round trip that varies. Nine profiles span what the real
+ * one has been seen to do. Feeding it a kind, punctual API proves nothing —
+ * against one, three separate breakages of this code go unnoticed.
+ */
+
+const assert = require('assert');
+const { createPlayhead, surroundingCues, positionToMs, msToPosition } = require('./resi');
+
+let passed = 0;
+function test(name, fn) {
+  fn();
+  passed++;
+  console.log(`  ok  ${name}`);
+}
+
+/* ── the simulated world ───────────────────────────────────────────────── */
+
+function makeWorld({ cadence, lag, jitter, net }) {
+  let seed = 12345;
+  const rnd = () => {
+    seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+    return seed / 0x7fffffff;
+  };
+  const w = {
+    t: 1700000000000,
+    media: 8 * 60000 + 48000,
+    playing: true,
+    published: 0,
+    lastPublish: 0,
+    nextCadence: cadence,
+  };
+  w.published = w.media - lag;
+  w.lastPublish = w.t;
+  w.advance = (ms) => {
+    for (let i = 0; i < ms; i += 100) {
+      w.t += 100;
+      if (w.playing) w.media += 100;
+      if (w.t - w.lastPublish >= w.nextCadence) {
+        w.lastPublish = w.t;
+        w.published = w.media - lag;
+        w.nextCadence = Math.max(500, cadence + Math.round((rnd() - 0.5) * 2 * jitter));
+      }
+    }
+  };
+  // A poll reads what Resi had when the request left, and the round trip costs time.
+  w.poll = () => {
+    const body = w.published;
+    if (net) w.advance(100 + Math.round(rnd() * net));
+    return body;
+  };
+  return w;
+}
+
+const CUES = [
+  { name: 'Welcome', ms: 5 * 60000 },
+  { name: 'Campus Host', ms: 12 * 60000 + 30000 },
+  { name: 'Message', ms: 41 * 60000 },
+  { name: 'Closing', ms: 45 * 60000 },
+];
+
+function runProfile(cadence, lag, jitter, net) {
+  const w = makeWorld({ cadence, lag, jitter, net });
+  const head = createPlayhead({ now: () => w.t });
+  const tol = lag + 1200 + jitter + net * 0.35;
+  const label = `cadence ${cadence} lag ${lag} jitter ${jitter} net ${net}`;
+
+  const second = () => { w.advance(1000); head.note(w.poll()); return head.read(); };
+  const seconds = (n) => { let r; for (let i = 0; i < n; i++) r = second(); return r; };
+
+  test(`${label}: locks on, and beats the raw reading it is built from`, () => {
+    seconds(40);
+    let worstEst = 0;
+    let worstRaw = 0;
+    for (let i = 0; i < 30; i++) {
+      const { estMs } = second();
+      worstEst = Math.max(worstEst, w.media - estMs);
+      worstRaw = Math.max(worstRaw, w.media - w.published);
+    }
+    assert.ok(worstEst <= tol, `estimate drifted ${Math.round(worstEst)}ms (allowed ${Math.round(tol)})`);
+    if (cadence >= 2000) {
+      assert.ok(worstRaw >= cadence * 0.4,
+        `fixture is too kind: the raw value only went ${Math.round(worstRaw)}ms stale`);
+    }
+    assert.ok(head.read().playing, 'should read as playing');
+  });
+
+  test(`${label}: ticks every second and never runs backwards`, () => {
+    let prev = head.read().estMs;
+    let stalls = 0;
+    let backwards = 0;
+    for (let i = 0; i < 200; i++) {
+      const { estMs } = second();
+      if (estMs === prev) stalls++;
+      if (estMs < prev) backwards++;
+      prev = estMs;
+    }
+    assert.strictEqual(stalls, 0, 'the playhead stalled');
+    assert.strictEqual(backwards, 0, 'the playhead went backwards');
+  });
+
+  test(`${label}: follows a fired cue, and rolls over the one it passes`, () => {
+    w.media = 40 * 60000 + 50000;             // decoder jumps; Resi says nothing yet
+    let reported = false;
+    for (let i = 0; i < 60 && !reported; i++) {
+      second();
+      reported = Math.abs((head.read().estMs || 0) - w.media) < 8000;
+    }
+    assert.ok(reported, 'the jump was never picked up');
+    assert.ok(head.takeSeek(), 'the jump was not flagged as a seek');
+    const { estMs } = head.read();
+    assert.ok(Math.abs(estMs - w.media) <= tol + cadence / 2,
+      `resynced ${Math.round(w.media - estMs)}ms off`);
+    assert.ok(w.media - estMs >= -400, 'overshot the new playhead');
+    assert.strictEqual(surroundingCues(CUES, estMs).next.name, 'Message');
+    const after = seconds(15);
+    assert.strictEqual(surroundingCues(CUES, after.estMs).next.name, 'Closing');
+    assert.strictEqual(surroundingCues(CUES, after.estMs).prev.name, 'Message');
+  });
+
+  test(`${label}: follows a seek backwards`, () => {
+    w.media = 6 * 60000;
+    for (let i = 0; i < 60 && Math.abs((head.read().estMs || 0) - w.media) > 8000; i++) second();
+    const { estMs } = head.read();
+    assert.ok(Math.abs(estMs - w.media) <= tol + cadence / 2, 'did not follow the seek back');
+    assert.strictEqual(surroundingCues(CUES, estMs).next.name, 'Campus Host');
+  });
+
+  test(`${label}: freezes on a real pause and re-locks on resume`, () => {
+    w.playing = false;
+    const stoppedAt = w.media;
+    const wait = Math.ceil((Math.max(15000, Math.min(45000, (cadence + jitter) * 2.5 + 6000))
+      + cadence + jitter + 6000) / 1000);
+    let r = seconds(wait);
+    assert.strictEqual(r.playing, false, 'did not notice the pause');
+    const held = r.estMs;
+    r = seconds(20);
+    assert.strictEqual(r.estMs, held, 'kept counting while paused');
+
+    w.playing = true;
+    r = seconds(25);
+    assert.strictEqual(r.playing, true, 'did not notice the resume');
+    assert.ok(Math.abs(r.estMs - w.media) <= tol + cadence, 're-locked in the wrong place');
+    assert.ok(held - stoppedAt <= 45000 + cadence + jitter + 2 * net + 3000,
+      'the frozen position crept instead of stopping');
+  });
+
+  test(`${label}: survives a pause longer than the offset window`, () => {
+    w.playing = false;
+    let r = seconds(150);
+    assert.strictEqual(r.playing, false, 'should still read as paused');
+    assert.ok(r.estMs !== null && r.estMs !== undefined, 'lost the position entirely');
+    w.playing = true;
+    head.takeSeek();
+    r = seconds(30);
+    assert.strictEqual(r.playing, true, 'did not recover');
+    assert.ok(Math.abs(r.estMs - w.media) <= tol + cadence, 're-locked in the wrong place');
+    assert.ok(head.takeSeek(), 'a resume after a long pause must flag as a seek');
+  });
+}
+
+/* ── the plain bits ────────────────────────────────────────────────────── */
+
+test('positionToMs reads Resi positions, and rejects anything else', () => {
+  assert.strictEqual(positionToMs('00:00:00.000'), 0);
+  assert.strictEqual(positionToMs('01:02:03.500'), 3723500);
+  assert.strictEqual(positionToMs('00:00:01'), 1000);
+  assert.strictEqual(positionToMs(''), null);
+  assert.strictEqual(positionToMs('garbage'), null);
+  assert.strictEqual(positionToMs(null), null);
+  assert.strictEqual(positionToMs(undefined), null);
+});
+
+test('msToPosition round-trips', () => {
+  for (const ms of [0, 1500, 3723500, 36000000]) {
+    assert.strictEqual(positionToMs(msToPosition(ms)), ms);
+  }
+});
+
+test('surroundingCues puts a cue you are exactly on behind you', () => {
+  assert.strictEqual(surroundingCues(CUES, 12 * 60000 + 30000).next.name, 'Message');
+  assert.strictEqual(surroundingCues(CUES, 12 * 60000 + 30000).prev.name, 'Campus Host');
+  assert.strictEqual(surroundingCues(CUES, 0).prev, null);
+  assert.strictEqual(surroundingCues(CUES, 60 * 60000).next, null);
+  assert.strictEqual(surroundingCues([], 1000).next, null);
+});
+
+/* ── starting partway through Resi's cycle ─────────────────────────────── */
+
+// Seen live at North Attleboro: Resi publishing every ~30s, and the board starting a
+// few seconds before a publish. The first "gap" it measured was 2s (9s after a
+// reboot), and once that was the cadence every honest 30s gap was thrown out as a
+// pause gap -- so playback read as paused 15s into every update, the countdown froze,
+// and the next cue (and its name) stopped moving on.
+for (const [into, burst] of [[28000, false], [21000, false], [0, true]]) {
+  test(`30s Resi, started ${into / 1000}s into its cycle${burst ? ', 2s burst after a seek' : ''}: never falsely paused`, () => {
+    const w = makeWorld({ cadence: 30000, lag: 1000, jitter: 2000, net: 500 });
+    w.lastPublish = w.t - into;
+    const head = createPlayhead({ now: () => w.t });
+    const second = () => { w.advance(1000); head.note(w.poll()); return head.read(); };
+    let paused = 0;
+    for (let i = 0; i < 100; i++) if (!second().playing) paused++;
+    if (burst) {
+      w.media += 15 * 60000;                       // a seek, published at once...
+      w.lastPublish = w.t - w.nextCadence;
+      second(); second();
+      w.lastPublish = w.t - w.nextCadence;          // ...and again 2s later
+    }
+    for (let i = 0; i < 300; i++) if (!second().playing) paused++;
+    assert.strictEqual(paused, 0, `read as paused for ${paused}s while playing`);
+  });
+}
+
+/* ── the matrix ────────────────────────────────────────────────────────── */
+
+const argv = process.argv.slice(2).map(Number);
+const PROFILES = argv.length >= 4 ? [argv.slice(0, 4)] : [
+  [5000, 500, 0, 0], [5000, 500, 0, 2500], [2000, 0, 0, 800],
+  [10000, 3000, 0, 2500], [7000, 1000, 4000, 2000], [3000, 500, 2000, 1000],
+  [12000, 2000, 6000, 3000], [1000, 0, 0, 0], [8000, 1500, 3000, 4000],
+];
+for (const [cadence, lag, jitter, net] of PROFILES) runProfile(cadence, lag, jitter, net);
+
+console.log(`\n${passed} tests passed`);

modules/resi-cues/server.js

@@ -0,0 +1,372 @@
+/* Resi Cues — server entry.
+ *
+ * Follows one Resi decoder and works out how long until its next cue point, then
+ * offers that two ways:
+ *
+ *   GET  /state         → snapshot for this module's tile
+ *   GET  /stream        → SSE, `state` events on every change
+ *   GET  /timers        → snapshot for the Timers module (guide: "Offering
+ *   GET  /timers/stream → SSE, `timers` events        timers to the Timers module")
+ *   GET  /decoders      → optionsRoute for the admin page's decoder picker
+ *
+ * Both the cue list and the playhead come from Resi's cloud rather than the
+ * decoder: the decoder reports its position upstream and central.resi.io hands it
+ * back. Nothing is installed at the decoder end, and nothing here talks to the
+ * decoder directly.
+ *
+ * Why the playhead is estimated rather than repeated is explained in resi.js.
+ */
+
+'use strict';
+
+const { createResiClient, createPlayhead, surroundingCues, positionToMs } = require('./resi');
+
+const HEARTBEAT_MS = 15000;
+
+function json(res, code, body) {
+  const text = JSON.stringify(body);
+  res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(text);
+}
+
+function sseHead(res) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream; charset=utf-8',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+  });
+  res.write('retry: 3000\n\n');
+}
+
+function writeAll(set, chunk) {
+  for (const res of set) {
+    try {
+      res.write(chunk);
+    } catch {
+      set.delete(res);
+    }
+  }
+}
+
+/** What the tile and the Timers module see before anything has been configured. */
+function emptyState(message) {
+  return {
+    status: 'error',
+    message: message || 'Not configured',
+    decoder: '',
+    event: '',
+    playing: false,
+    estMs: null,
+    estAt: Date.now(),
+    cadenceMs: 0,
+    next: null,
+    prev: null,
+    cues: [],
+  };
+}
+
+function emptyTimers(now) {
+  return { source: 'resi-cues', label: 'Resi', updatedAt: now, timers: [] };
+}
+
+let current = null; // the live handle, shared with routes()
+let pickerClient = null; // { key, client } for the decoder picker when the module isn't running those credentials
+
+module.exports = {
+  init({ config, log }) {
+    const username = String(config.username || '').trim();
+    const password = String(config.password || '');
+    const wanted = String(config.player || '').trim();
+    const pollMs = Math.max(250, Number(config.pollSeconds || 1) * 1000);
+    const cueRefreshMs = Math.max(1000, Number(config.cueRefreshSeconds || 5) * 1000);
+
+    const stateStreams = new Set();
+    const timerStreams = new Set();
+    let state = emptyState(username && password ? 'Connecting' : 'Enter the Resi login in admin');
+    let timer = null;
+    let heartbeat = null;
+    let stopped = false;
+
+    const resi = createResiClient({ username, password });
+    const head = createPlayhead({ trimMs: Number(config.positionTrimMs || 0) });
+
+    let venueUuid = '';
+    let hardwareId = '';
+    let decoderName = '';
+    let eventId = '';
+    let profileId = '';
+    let eventName = '';
+    let cues = [];
+    let lastCueLoad = 0;
+    let inFlight = false;
+
+    /* — what the two consumers see — */
+
+    function publishState(next) {
+      const before = JSON.stringify(state);
+      state = next;
+      if (JSON.stringify(state) === before) return;
+      writeAll(stateStreams, `event: state\ndata: ${JSON.stringify(state)}\n\n`);
+    }
+
+    /**
+     * The Timers module extrapolates from `startedAt` and its own clock, so this
+     * only has to change when a timer changes *structurally* — a new cue, a pause,
+     * a seek. Broadcasting every poll would make every dashboard repaint at 1 Hz
+     * for nothing.
+     */
+    function timersSignature(snap) {
+      return JSON.stringify(snap.timers.map(
+        (t) => [t.id, t.label, t.state, t.startedAt, t.targetMs, t.status && t.status.text]));
+    }
+
+    let lastTimerSig = '';
+    function publishTimers() {
+      const snap = timersSnapshot(Date.now());
+      const sig = timersSignature(snap);
+      if (sig === lastTimerSig) return;
+      lastTimerSig = sig;
+      writeAll(timerStreams, `event: timers\ndata: ${JSON.stringify(snap)}\n\n`);
+    }
+
+    function timersSnapshot(now) {
+      const timers = [];
+      if (state.estMs !== null && state.estMs !== undefined) {
+        const est = state.estMs + (state.playing ? now - state.estAt : 0);
+        if (state.next) {
+          const remainingMs = Math.max(0, state.next.ms - est);
+          // The countdown "runs" from the cue before it, which is what gives the
+          // consumer something to colour progress against.
+          const from = state.prev ? state.prev.ms : 0;
+          timers.push({
+            id: 'next-cue',
+            label: state.next.name || 'Next cue',
+            kind: 'countdown',
+            state: state.playing ? 'running' : 'paused',
+            startedAt: now - Math.max(0, est - from),
+            elapsedMs: null,
+            remainingMs,
+            targetMs: Math.max(1000, state.next.ms - from),
+            // The label already is the cue's name, and it is what the card is titled
+            // with; repeating it on the status line only crowded the card.
+            status: { text: state.playing ? 'Next cue' : 'Held', tone: state.playing ? 'ok' : 'warn' },
+            detail: state.event || '',
+          });
+        }
+        timers.push({
+          id: 'playhead',
+          label: 'Playhead',
+          kind: 'elapsed',
+          state: state.playing ? 'running' : 'paused',
+          startedAt: now - Math.max(0, est),
+          elapsedMs: Math.max(0, est),
+          remainingMs: null,
+          targetMs: null,
+          status: { text: state.decoder || '', tone: state.playing ? 'ok' : 'muted' },
+          detail: state.prev ? `After ${state.prev.name}` : '',
+        });
+      }
+      return { source: 'resi-cues', label: 'Resi', updatedAt: now, timers };
+    }
+
+    /* — finding the decoder — */
+
+    async function locate() {
+      const venues = await resi.venues();
+      for (const v of venues) {
+        const players = await resi.players(v.uuid);
+        for (const p of players) {
+          if (wanted ? p.playerHardwareId === wanted : true) {
+            venueUuid = v.uuid;
+            hardwareId = p.playerHardwareId;
+            decoderName = `${v.userName || v.name || 'Venue'} — ${p.userName || hardwareId}`;
+            return true;
+          }
+        }
+      }
+      return false;
+    }
+
+    /* — the loop — */
+
+    async function tick() {
+      if (inFlight || stopped) return;
+      inFlight = true;
+      try {
+        if (!hardwareId && !(await locate())) {
+          publishState(emptyState(wanted ? 'That decoder is not on this account' : 'No decoders found'));
+          return;
+        }
+
+        const players = await resi.players(venueUuid);
+        const me = players.find((p) => p.playerHardwareId === hardwareId);
+        if (!me) {
+          publishState({ ...emptyState('Decoder not listed'), decoder: decoderName });
+          return;
+        }
+
+        head.note(positionToMs(me.position));
+
+        if (me.eventId && me.eventId !== eventId) {
+          eventId = me.eventId;
+          const ev = (await resi.event(eventId)) || {};
+          profileId = ev.eventProfileId || '';
+          eventName = ev.name || '';
+          cues = profileId ? await resi.cues(profileId, eventId) : [];
+          lastCueLoad = Date.now();
+          log(`event ${eventName || eventId} — ${cues.length} cue(s)`);
+        } else if (!me.eventId) {
+          eventId = '';
+          profileId = '';
+          eventName = '';
+          cues = [];
+        }
+
+        const seeked = head.takeSeek();
+        if (profileId && eventId && (seeked || Date.now() - lastCueLoad >= cueRefreshMs)) {
+          lastCueLoad = Date.now();
+          const fresh = await resi.cues(profileId, eventId);
+          if (JSON.stringify(fresh) !== JSON.stringify(cues)) {
+            log(`cue list changed — ${fresh.length} cue(s)`);
+            cues = fresh;
+          }
+        }
+
+        const { estMs, playing, cadenceMs } = head.read();
+        const { prev, next } = surroundingCues(cues, estMs === null ? -1 : estMs);
+        publishState({
+          status: 'ok',
+          message: '',
+          decoder: decoderName,
+          event: eventName,
+          playing,
+          estMs,
+          estAt: Date.now(),
+          cadenceMs,
+          next,
+          prev,
+          cues,
+        });
+      } catch (err) {
+        const message = (err && err.message) || String(err);
+        log(`poll failed: ${message}`);
+        publishState({ ...state, status: 'error', message });
+      } finally {
+        inFlight = false;
+        publishTimers();
+      }
+    }
+
+    if (username && password) {
+      timer = setInterval(() => { void tick(); }, pollMs);
+      void tick();
+    } else {
+      log('no Resi login configured — idle');
+    }
+    heartbeat = setInterval(() => {
+      writeAll(stateStreams, ': ping\n\n');
+      writeAll(timerStreams, ': ping\n\n');
+    }, HEARTBEAT_MS);
+
+    current = {
+      get state() { return state; },
+      timersSnapshot,
+      stateStreams,
+      timerStreams,
+      resi,
+      credentialsKey: `${username}\n${password}`,
+      configured: Boolean(username && password),
+      stop() {
+        stopped = true;
+        if (timer) clearInterval(timer);
+        if (heartbeat) clearInterval(heartbeat);
+        for (const res of [...stateStreams, ...timerStreams]) {
+          try { res.end(); } catch { /* already gone */ }
+        }
+        stateStreams.clear();
+        timerStreams.clear();
+        if (current && current.stop === this.stop) current = null;
+      },
+      health() {
+        if (!username || !password) return { status: 'error', message: 'Enter the Resi login in admin' };
+        if (state.status === 'ok') {
+          return { status: 'ok', message: state.playing ? `Playing — ${state.decoder}` : `Paused — ${state.decoder}` };
+        }
+        if (state.status === 'error') return { status: 'error', message: state.message };
+        return { status: 'connecting', message: state.message };
+      },
+    };
+    return current;
+  },
+
+  routes({ config, log }) {
+    return {
+      'GET /state': (req, res) => {
+        json(res, 200, current ? current.state : emptyState('Module restarting'));
+      },
+
+      'GET /stream': (req, res) => {
+        sseHead(res);
+        const snap = current ? current.state : emptyState('Module restarting');
+        res.write(`event: state\ndata: ${JSON.stringify(snap)}\n\n`);
+        if (!current) return res.end();
+        current.stateStreams.add(res);
+        req.on('close', () => current && current.stateStreams.delete(res));
+      },
+
+      'GET /timers': (req, res) => {
+        const now = Date.now();
+        json(res, 200, current ? current.timersSnapshot(now) : emptyTimers(now));
+      },
+
+      'GET /timers/stream': (req, res) => {
+        sseHead(res);
+        const now = Date.now();
+        const snap = current ? current.timersSnapshot(now) : emptyTimers(now);
+        res.write(`event: timers\ndata: ${JSON.stringify(snap)}\n\n`);
+        if (!current) return res.end();
+        current.timerStreams.add(res);
+        req.on('close', () => current && current.timerStreams.delete(res));
+      },
+
+      // The admin page's decoder picker. A live call, because it is how the decoder
+      // gets chosen in the first place — there is nothing cached to answer from.
+      'GET /decoders': async (req, res) => {
+        if (!config.username || !config.password) {
+          return json(res, 200, { options: [], note: 'Enter the Resi login first' });
+        }
+        try {
+          // The running module's client when it has these credentials, else one kept
+          // per login: a fresh client per request signed in on every admin page load,
+          // and its own hold-off never applied -- which kept Resi rate-limiting.
+          const username = String(config.username).trim();
+          const key = `${username}\n${config.password}`;
+          let client;
+          if (current && current.resi && current.credentialsKey === key) client = current.resi;
+          else {
+            if (!pickerClient || pickerClient.key !== key) {
+              pickerClient = { key, client: createResiClient({
+                username, password: String(config.password),
+              }) };
+            }
+            client = pickerClient.client;
+          }
+          const options = [];
+          for (const v of await client.venues()) {
+            for (const p of await client.players(v.uuid)) {
+              options.push({
+                value: p.playerHardwareId,
+                label: `${p.userName || p.playerHardwareId}`,
+                group: v.userName || v.name || 'Venue',
+              });
+            }
+          }
+          json(res, 200, { options });
+        } catch (err) {
+          log(`decoder list failed: ${(err && err.message) || err}`);
+          json(res, 502, { options: [], error: (err && err.message) || String(err) });
+        }
+      },
+    };
+  },
+};

modules/resi-cues/server.test.js

@@ -0,0 +1,280 @@
+'use strict';
+
+/**
+ * Server-entry tests for Resi Cues.
+ *
+ *   node modules/resi-cues/server.test.js
+ *
+ * Plain Node, no dependencies; exits non-zero on the first failure. Resi is
+ * replaced with a canned account — a venue, a decoder on an event, four cue
+ * points — so this covers the parts `resi.test.js` cannot: signing in, finding
+ * the decoder, following the event, and the two snapshots other things read
+ * (`/state` for the tile, `/timers` for the Timers module).
+ *
+ * Nothing here reaches the network, and the poll interval is captured rather
+ * than run, so the test drives the loop a tick at a time.
+ */
+
+const assert = require('assert');
+
+let passed = 0;
+// Awaited, so an async test finishes before the next one changes the world under it.
+async function test(name, fn) {
+  await fn();
+  passed++;
+  console.log(`  ok  ${name}`);
+}
+
+/* ── a canned Resi account ─────────────────────────────────────────────── */
+
+const CUES = [
+  { name: 'Welcome', position: '00:05:00.000' },
+  { name: 'Campus Host', position: '00:12:30.000' },
+  { name: 'Message', position: '00:41:00.000' },
+];
+
+const world = { position: '00:08:48.000', eventId: 'EV1', logins: 0, playerCalls: 0 };
+
+function reply(body, extra) {
+  return Object.assign({
+    ok: true,
+    status: 200,
+    headers: { get: () => null, getSetCookie: () => [] },
+    json: async () => body,
+  }, extra || {});
+}
+
+globalThis.fetch = async (url) => {
+  const path = String(url).replace('https://central.resi.io', '').split('?')[0];
+  if (path === '/api/v3/login') {
+    world.logins++;
+    return reply({}, { headers: { get: () => null, getSetCookie: () => ['livingas1=TOKEN; Path=/'] } });
+  }
+  if (path === '/api_v2.svc/users/me') return reply({ customerId: 'CUST', userName: 'tester' });
+  if (path === '/api/v3/customers/CUST/venues') return reply([{ uuid: 'V1', userName: 'Main' }]);
+  if (path === '/api_v2.svc/users/V1/players') {
+    world.playerCalls++;
+    return reply([{ playerHardwareId: 'DEC1', userName: 'Lobby', position: world.position, eventId: world.eventId }]);
+  }
+  if (path === '/api/v3/customers/CUST/events/EV1') {
+    return reply({ name: 'Sunday 9am', eventProfileId: 'P1' });
+  }
+  if (path === '/api_v2.svc/streamprofiles/P1/events/EV1/cues') return reply(CUES);
+  return reply({}, { ok: false, status: 404 });
+};
+
+/* ── the shell, as much of it as the module touches ────────────────────── */
+
+const realSetInterval = globalThis.setInterval;
+const realClearInterval = globalThis.clearInterval;
+let tickFn = null;
+globalThis.setInterval = (fn, ms) => {
+  if (!tickFn) tickFn = fn;          // the poll; the heartbeat is the second one
+  return { fn, ms };
+};
+globalThis.clearInterval = () => {};
+
+const server = require('./server');
+const logged = [];
+const handle = server.init({
+  config: { username: 'a@b.c', password: 'secret', player: 'DEC1', pollSeconds: 1, cueRefreshSeconds: 5 },
+  log: (m) => logged.push(m),
+});
+
+/** Let the poll's promise chain finish; nothing here waits on real time. */
+async function settle() {
+  for (let i = 0; i < 60; i++) await Promise.resolve();
+}
+
+function collect(route, req) {
+  const res = {
+    code: 0, headers: null, body: '',
+    writeHead(code, headers) { this.code = code; this.headers = headers; },
+    write(chunk) { this.body += chunk; },
+    end(chunk) { if (chunk) this.body += chunk; },
+  };
+  route(req || { on() {} }, res);
+  return res;
+}
+
+(async () => {
+  await settle();
+
+  const routes = server.routes({ config: {}, log: (m) => logged.push(m) });
+
+  await test('signs in once and finds the configured decoder', () => {
+    assert.strictEqual(world.logins, 1, 'should sign in exactly once');
+    const state = handle.state;
+    assert.strictEqual(state.status, 'ok', state.message);
+    assert.strictEqual(state.decoder, 'Main — Lobby');
+    assert.strictEqual(state.event, 'Sunday 9am');
+    assert.strictEqual(state.cues.length, 3);
+  });
+
+  await test('works out the cue either side of the playhead', () => {
+    const state = handle.state;
+    assert.strictEqual(state.next.name, 'Campus Host');
+    assert.strictEqual(state.prev.name, 'Welcome');
+    assert.ok(Math.abs(state.estMs - 528000) < 2000, `playhead was ${state.estMs}`);
+  });
+
+  await test('/state answers the same snapshot as the stream', () => {
+    const res = collect(routes['GET /state']);
+    assert.strictEqual(res.code, 200);
+    assert.deepStrictEqual(JSON.parse(res.body), handle.state);
+  });
+
+  await test('/stream opens with an event so a new tile paints at once', () => {
+    const res = collect(routes['GET /stream']);
+    assert.strictEqual(res.code, 200);
+    assert.strictEqual(res.headers['Content-Type'], 'text/event-stream; charset=utf-8');
+    assert.ok(res.body.includes('retry: 3000'), 'should set a retry');
+    assert.ok(res.body.includes('event: state'), 'should send an initial state event');
+  });
+
+  await test('/timers offers the countdown and the playhead, shaped as the guide says', () => {
+    const snap = JSON.parse(collect(routes['GET /timers']).body);
+    assert.strictEqual(snap.source, 'resi-cues');
+    assert.strictEqual(snap.label, 'Resi');
+    assert.ok(snap.updatedAt > 0);
+    const [next, playhead] = snap.timers;
+
+    assert.strictEqual(next.id, 'next-cue');
+    assert.strictEqual(next.kind, 'countdown');
+    assert.strictEqual(next.state, 'running');
+    assert.strictEqual(next.label, 'Campus Host');
+    assert.ok(Math.abs(next.remainingMs - 222000) < 2000, `remaining was ${next.remainingMs}`);
+    // the countdown runs from the cue before it, so a consumer can colour progress
+    assert.strictEqual(next.targetMs, 450000);
+    assert.strictEqual(next.status.text, 'Next cue');   // the name is the label; not repeated
+    assert.ok(next.startedAt <= snap.updatedAt, 'startedAt must be in the past');
+
+    assert.strictEqual(playhead.id, 'playhead');
+    assert.strictEqual(playhead.kind, 'elapsed');
+    assert.strictEqual(playhead.remainingMs, null);
+    assert.ok(Math.abs(playhead.elapsedMs - 528000) < 2000);
+  });
+
+  await test('a cue fired at the host moves the countdown on the next poll', async () => {
+    world.position = '00:12:40.000';         // jumped past Campus Host
+    tickFn();
+    await settle();
+    const state = handle.state;
+    assert.strictEqual(state.next.name, 'Message');
+    assert.strictEqual(state.prev.name, 'Campus Host');
+    const snap = JSON.parse(collect(routes['GET /timers']).body);
+    assert.strictEqual(snap.timers[0].label, 'Message');   // the card's name follows the cue
+  });
+
+  await test('a decoder with no event reports nothing playing rather than stale cues', async () => {
+    world.eventId = '';
+    tickFn();
+    await settle();
+    assert.strictEqual(handle.state.next, null);
+    assert.deepStrictEqual(handle.state.cues, []);
+    assert.strictEqual(handle.state.event, '');
+  });
+
+  await test('health speaks about the upstream, not about itself', () => {
+    const h = handle.health();
+    assert.ok(['ok', 'connecting', 'error'].includes(h.status), h.status);
+    assert.ok(h.message.length > 0, 'health should say something useful');
+  });
+
+  await test('an unconfigured module idles instead of hammering Resi', () => {
+    const before = world.logins;
+    const idle = server.init({ config: {}, log: () => {} });
+    assert.strictEqual(world.logins, before, 'must not sign in with no credentials');
+    assert.strictEqual(idle.health().status, 'error');
+    assert.ok(/login/i.test(idle.health().message), idle.health().message);
+    idle.stop();
+  });
+
+  await test('stop() leaves nothing running', () => {
+    handle.stop();
+    const res = collect(routes['GET /state']);
+    assert.strictEqual(JSON.parse(res.body).status, 'error');
+  });
+
+  // Seen live at North Attleboro: a failed login was retried on every 1s poll, so
+  // Resi answered 429 and kept answering it, and the decoder picker stayed empty.
+  await test('a failed login holds off instead of retrying every poll', async () => {
+    const { createResiClient } = require('./resi');
+    let t = 1700000000000;
+    let logins = 0;
+    let limited = true;
+    const client = createResiClient({
+      username: 'a@b.c',
+      password: 'secret',
+      now: () => t,
+      fetch: async (url) => {
+        const path = String(url).replace('https://central.resi.io', '').split('?')[0];
+        if (path === '/api/v3/login') {
+          logins++;
+          if (limited) return reply({}, { ok: false, status: 429 });
+          return reply({}, { headers: { get: () => null, getSetCookie: () => ['livingas1=T; Path=/'] } });
+        }
+        if (path === '/api_v2.svc/users/me') return reply({ customerId: 'CUST' });
+        if (path === '/api/v3/customers/CUST/venues') return reply([{ uuid: 'V1' }]);
+        return reply({}, { ok: false, status: 404 });
+      },
+    });
+    const poll = async () => { try { await client.venues(); return 'ok'; } catch (e) { return e.message; } };
+
+    assert.match(await poll(), /rate-limiting/);
+    for (let i = 0; i < 60; i++) { t += 1000; await poll(); }   // a minute of 1s polls
+    assert.ok(logins <= 3, `signed in ${logins} times in a minute while rate-limited`);
+    assert.match(await poll(), /retrying in \d+s/, 'the wait is shown, not hidden');
+
+    limited = false;
+    t += 5 * 60000;                                             // past the longest hold-off
+    assert.strictEqual(await poll(), 'ok', 'recovers once Resi lets it in');
+    const after = logins;
+    for (let i = 0; i < 30; i++) { t += 1000; await poll(); }
+    assert.strictEqual(logins, after, 'a good session is not signed in again');
+  });
+
+  await test('a rejected password says so', async () => {
+    const { createResiClient } = require('./resi');
+    const client = createResiClient({
+      username: 'a@b.c', password: 'wrong', now: () => 0,
+      fetch: async () => reply({}, { ok: false, status: 400 }),
+    });
+    await assert.rejects(client.venues(), /check the password/);
+  });
+
+  // Seen live: media@waters.church signs in fine but may not list venues (403). The
+  // client answered every 403 by signing in again -- a fresh login on every poll.
+  await test('a login that may not see venues is held off, not signed in every poll', async () => {
+    const { createResiClient } = require('./resi');
+    let t = 1700000000000;
+    let logins = 0;
+    let venueCalls = 0;
+    const client = createResiClient({
+      username: 'a@b.c', password: 'secret', now: () => t,
+      fetch: async (url) => {
+        const path = String(url).replace('https://central.resi.io', '').split('?')[0];
+        if (path === '/api/v3/login') {
+          logins++;
+          return reply({}, { headers: { get: () => null, getSetCookie: () => ['livingas1=T; Path=/'] } });
+        }
+        if (path === '/api_v2.svc/users/me') return reply({ customerId: 'CUST' });
+        if (path === '/api/v3/customers/CUST/venues') { venueCalls++; return reply({}, { ok: false, status: 403 }); }
+        return reply({}, { ok: false, status: 404 });
+      },
+    });
+    const poll = async () => { try { await client.venues(); return 'ok'; } catch (e) { return e.message; } };
+
+    assert.match(await poll(), /isn't allowed to see its venues \(403\)/);
+    for (let i = 0; i < 120; i++) { t += 1000; await poll(); }   // two minutes of 1s polls
+    // At most one renewal once the session is over a minute old (in case it really
+    // had expired), then the hold-off keeps growing -- not one sign-in per poll.
+    assert.ok(logins <= 2, `signed in ${logins} times in two minutes for a permission problem`);
+    assert.ok(venueCalls <= 8, `asked for venues ${venueCalls} times in two minutes (a poll each would be 121)`);
+    assert.match(await poll(), /ask a Resi admin/);
+  });
+
+  globalThis.setInterval = realSetInterval;
+  globalThis.clearInterval = realClearInterval;
+  console.log(`\n${passed} tests passed`);
+})();

modules/resi-cues/style.css

@@ -0,0 +1,113 @@
+/* Resi Cues — scoped under its tile via [data-module="resi-cues"], styled with
+   the shell's CSS variables only.
+
+   The countdown is sized in cqmin so it fills whatever the tile is given: the
+   same module is a small strip on a busy dashboard and a wall panel on its own. */
+
+[data-module="resi-cues"] {
+  container-type: size;
+}
+
+[data-module="resi-cues"] .resi-wrap {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.35em;
+  padding: 2%;
+  text-align: center;
+  overflow: hidden;
+}
+
+[data-module="resi-cues"] .resi-label {
+  color: var(--muted);
+  font-size: clamp(0.6rem, 5cqmin, 1rem);
+  font-weight: 700;
+  letter-spacing: 0.14em;
+  line-height: 1;
+}
+
+[data-module="resi-cues"] .resi-cue {
+  color: var(--text);
+  font-size: clamp(0.85rem, 11cqmin, 2.6rem);
+  font-weight: 650;
+  line-height: 1.05;
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+[data-module="resi-cues"] .resi-count {
+  color: var(--accent);
+  font-size: clamp(1.4rem, 30cqmin, 9rem);
+  font-weight: 700;
+  font-variant-numeric: tabular-nums;
+  letter-spacing: 0.01em;
+  line-height: 1;
+}
+
+[data-module="resi-cues"] .resi-count.is-soon { color: var(--warn); }
+
+/* Held rather than counting: the digits are still true, they just are not moving. */
+[data-module="resi-cues"] .resi-count.is-held,
+[data-module="resi-cues"] .resi-foot-item.is-held {
+  color: var(--muted);
+}
+
+[data-module="resi-cues"] .resi-foot {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.2em 0.9em;
+  color: var(--muted);
+  font-size: clamp(0.6rem, 5cqmin, 0.95rem);
+  font-variant-numeric: tabular-nums;
+}
+
+[data-module="resi-cues"] .resi-list {
+  list-style: none;
+  margin: 0.4em 0 0;
+  padding: 0.4em 0 0;
+  width: 100%;
+  max-width: 28em;
+  border-top: 1px solid var(--border);
+  overflow-y: auto;
+  font-size: clamp(0.6rem, 4.5cqmin, 0.95rem);
+}
+
+[data-module="resi-cues"] .resi-list-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 1em;
+  padding: 0.12em 0.2em;
+  color: var(--text);
+}
+
+[data-module="resi-cues"] .resi-list-row.is-past { color: var(--muted); }
+
+[data-module="resi-cues"] .resi-list-row.is-next {
+  color: var(--accent);
+  font-weight: 650;
+}
+
+[data-module="resi-cues"] .resi-list-at { font-variant-numeric: tabular-nums; }
+
+[data-module="resi-cues"] .resi-list-name {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+[data-module="resi-cues"] .resi-empty {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 6%;
+  color: var(--muted);
+  text-align: center;
+}