Band Lineup's docs move to where every other module's live

Two things were out of place. `modules/band-lineup/README.md` was the only
README inside any of the eight modules — the guide's folder shape is manifest,
client, server, assets, and every other module is described in this README's
*Included modules* instead. It was also describing a module that no longer
exists: photos and birthdays "come from Planning Center", guests "pinned per
slot", and a refresh interval the manifest has never had.

The entry here had drifted the same way, calling the Drive folder somewhere
to put "manual photos" and the board something Planning Center fills. It is
the other way round now, and has been since 1.10: the board is shared server
state and the source of truth, the photo library fills it, and Sync is
auto-fill that only touches slots nobody placed by hand. The entry says that,
and picks up the Choir spot and the title-bar columns while it is there.

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

.gitignore

@@ -14,3 +14,6 @@ modules/propresenter-timers/ltc-capture
 # the launcher's build output, and its cache of the Node runtime it embeds
 launcher/macos/build/
 launcher/macos/.cache/
+
+# Compiled per-machine, source sits next to it (see spl-capture.swift).
+modules/spl-meter/spl-capture

CLAUDE.md

@@ -44,6 +44,7 @@ title-bar controls). The rules that matter most:
   for the existing upstreams: `node tools/prodcom-mock.js` (ProdCom) and
   `node band-lineup-display/tmp/pp-mock.js 1599` (ProPresenter).
   `node tools/slack-mock.js 24716` (Slack; run ProdDash with `SLACK_API_BASE=http://127.0.0.1:24716/api`).
+  `node tools/pco-band-mock.js 24710` (Planning Center for Band Lineup; run ProdDash with `BAND_LINEUP_API_BASE=http://127.0.0.1:24710`).
 
 ## Reference code (read-only forks — don't develop these here)
 

README.md

@@ -266,7 +266,21 @@ below. Nothing is installed without someone clicking.
   display options) — these belong to this browser's layout, not the server.
 - The **grid icon** — save the current arrangement to the server under a
   name, load a named layout (it becomes a local copy — browsers are never
-  linked), or reset this browser's dashboard.
+  linked), or reset this browser's dashboard. Loading says what it did —
+  *Loaded "FOH": 9 tiles, 2 not shown — Service, #ops aren't offered right
+  now* — with **Undo** in the message to get back the arrangement you had.
+  A tile whose module or picker entry isn't offered at the moment keeps its
+  place and shows nothing, then appears when it is; it is never replaced by
+  the module's default tile. Saving over an existing name asks first, and
+  the server keeps the copy it replaced: **Restore previous** in Admin →
+  Saved layouts swaps it back (and swapping again undoes that). The menu's
+  **Grid Size** stepper sets how many columns this browser cuts the board into —
+  8 to 24, 12 by default. Finer lets tiles be smaller so more fit across (a
+  4K wall), coarser suits a small screen read close up; row height follows,
+  so tiles keep their shape and simply change size. Going coarser, a tile
+  that no longer fits where it was moves to the first free spot rather than
+  onto another tile. It saves with the layout, so a named layout comes back
+  at the density it was arranged on.
 - Every tile has a **status dot**: green = live, amber = connecting,
   red = upstream unreachable (hover it for details). Tiles reconnect
   automatically.
@@ -314,7 +328,14 @@ below. Nothing is installed without someone clicking.
   description and item notes. When the ProPresenter module is running it
   follows that module's live item, highlights the matching plan item, dims
   what's done and shows the elapsed vs planned runtime and how far
-  ahead/behind the service is. Admin config is the connection: Planning
+  ahead/behind the service is. Items are matched by name — a document named
+  like the Planning Center item or its song, tags and all. The message is
+  the exception: a sermon's document is named after the sermon, so a live
+  document that reads like the plan itself — its date code, series title
+  and part, as in `260927 Where is Your Faith? - Part 6` — is taken as the
+  message and lands on the plan's message item (an item titled Message,
+  Sermon or Teaching, else the first item under such a header). Admin
+  config is the connection: Planning
   Center credentials (Personal Access Token app ID + secret, or an OAuth
   token), the service type (a list grouped by your Planning Center folders)
   and an optional pinned plan. Everything about the display is per tile
@@ -344,6 +365,24 @@ 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.
+- **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.
+  A photo library fills it: point the module at a Google Drive folder shared
+  "anyone with the link" (file name → person's name) or at a folder on the
+  ProdDash machine, and photos added or removed there follow. **Edit** in the
+  title bar opens that library — drag a photo onto a slot, drag between slots
+  to swap, rename or clear. Planning Center is optional auto-fill on top, not
+  the source of truth: **Sync** reads the upcoming plan's team members and
+  drops each into the slot matching their position, filling only slots nobody
+  placed by hand, so a guest pinned on Thursday survives Sunday's sync.
+  Birthdays in the service week (Wednesday→Tuesday) bring a gold glow and
+  raining confetti, and a Choir button adds the extra spot for the weeks there
+  is one. Admin config: Planning Center credentials, service type and plan, the
+  teams to include, the stage slots (one mic/pack label per line, in stage
+  order), default columns, and the photo folder. Tile settings: parallax,
+  names, mic labels, and birthday confetti with its intensity and a test
+  picker — columns are − / + in the title bar.
 - **Clock** — a big booth clock; also the smallest possible module and the
   reference for module authors.
 
@@ -355,8 +394,11 @@ timers + timecode on `127.0.0.1:1600`), `node tools/pco-mock.js`
 (Planning Center Services on `127.0.0.1:24700` — run ProdDash with
 `PCO_PLAN_API_BASE=http://127.0.0.1:24700`) and
 `node tools/slack-mock.js 24716` (the Slack Web API on `127.0.0.1:24716` —
-run ProdDash with `SLACK_API_BASE=http://127.0.0.1:24716/api`). See the
-testing section of the [module guide](docs/MODULE-GUIDE.md).
+run ProdDash with `SLACK_API_BASE=http://127.0.0.1:24716/api`) and
+`node tools/pco-band-mock.js 24710` (Planning Center for the Band Lineup
+board — a plan, its team members, birthdays and photos — run ProdDash with
+`BAND_LINEUP_API_BASE=http://127.0.0.1:24710`). See the testing section of
+the [module guide](docs/MODULE-GUIDE.md).
 
 ## Install as a desktop web app
 

band-lineup-display/index.html

@@ -57,9 +57,37 @@
                 <option value="">Choose service type</option>
               </select>
               <button type="button" class="btn btn-small" id="btn-pco-sync">Sync Upcoming</button>
+              <button type="button" class="btn btn-small" id="btn-pco-test-birthdays">Test Birthdays</button>
               <button type="button" class="btn btn-small" id="btn-pco-disconnect">Disconnect</button>
             </div>
             <div class="pco-status" id="pco-status">Planning Center is not connected.</div>
+            <div class="pco-status pco-birthday-result" id="pco-birthday-result"></div>
+
+            <div class="bday-block">
+              <div class="bday-head">
+                <span class="bday-title">Birthday Mode 🎂</span>
+                <label class="bday-switch">
+                  <input type="checkbox" id="bday-enabled" />
+                  <span class="bday-switch-label">On</span>
+                </label>
+              </div>
+              <div class="bday-controls" id="bday-controls">
+                <div class="bday-line">
+                  <span class="bday-line-label">Intensity</span>
+                  <div class="seg-inline" id="bday-intensity" role="group" aria-label="Birthday intensity">
+                    <button type="button" data-int="subtle">Subtle</button>
+                    <button type="button" data-int="full">Full</button>
+                  </div>
+                </div>
+                <div class="bday-line">
+                  <span class="bday-line-label">Force on <em>(test)</em></span>
+                  <select id="bday-test" class="pco-select bday-test-select" aria-label="Force birthday on a person for testing">
+                    <option value="">Off</option>
+                  </select>
+                </div>
+                <div class="bday-hint">Birthdays celebrate for the whole service week (Wednesday→Tuesday). Force is for testing only — it clears when the app restarts.</div>
+              </div>
+            </div>
             <div class="pco-position-builder">
               <select id="pco-position-option" class="pco-select" aria-label="Planning Center position">
                 <option value="">Choose position</option>

band-lineup-display/main.js

@@ -238,6 +238,47 @@ async function pcoRequestJson(target, credentials, searchParams) {
   return payload || { data: [] };
 }
 
+/**
+ * Like pcoRequestJson but never throws on an HTTP error — returns the status so callers can tell
+ * "no access" (401/403) apart from "no such record" (404) apart from success. Used by the People
+ * birthdate probe/fetch, where the whole point is to report what the token is actually allowed to do.
+ */
+async function pcoFetchStatus(target, credentials, searchParams) {
+  const url = buildPcoUrl(target, searchParams);
+  const response = await fetch(url, {
+    headers: {
+      Accept: 'application/json',
+      Authorization: pcoAuthHeader(credentials),
+      'User-Agent': pcoUserAgent(),
+    },
+  });
+  const text = await response.text();
+  let payload = null;
+  try {
+    payload = text ? JSON.parse(text) : null;
+  } catch {
+    payload = null;
+  }
+  return { status: response.status, ok: response.ok, payload };
+}
+
+/**
+ * Fetch one person's birthday from the People API as "MM-DD" (year discarded). Services and People
+ * share the same person id, so the Services person id we already store doubles as the People id.
+ * Returns { status, birthday, fieldPresent } — birthday '' when the field is null/absent.
+ */
+async function pcoFetchBirthday(personId, credentials) {
+  if (!personId) return { status: 0, birthday: '', fieldPresent: false };
+  const { status, ok, payload } = await pcoFetchStatus(
+    `/people/v2/people/${encodeURIComponent(personId)}`,
+    credentials,
+    { 'fields[Person]': 'birthdate' },
+  );
+  if (!ok) return { status, birthday: '', fieldPresent: false };
+  const attrs = payload?.data?.attributes || {};
+  return { status, birthday: normalizeBirthdayMmdd(attrs.birthdate), fieldPresent: 'birthdate' in attrs };
+}
+
 async function pcoFetchAll(target, credentials, searchParams) {
   let nextUrl = buildPcoUrl(target, searchParams).toString();
   const data = [];
@@ -275,6 +316,15 @@ function emptyState() {
     pcoDisplayPositions: [],
     proPresenter: { enabled: false, host: '', port: 0, playlistUuid: '', playlistName: '' },
     displayServer: { enabled: false, port: DEFAULT_DISPLAY_PORT },
+    birthdayMode: { enabled: true, intensity: 'subtle' },
+  };
+}
+
+/** Birthday Mode display settings (the per-person test override is NOT persisted — it lives only in the renderer). */
+function normalizeBirthdayMode(entry) {
+  return {
+    enabled: entry?.enabled === undefined ? true : Boolean(entry.enabled),
+    intensity: entry?.intensity === 'full' ? 'full' : 'subtle',
   };
 }
 
@@ -308,9 +358,26 @@ function normalizeSavedLibraryPerson(person) {
     source: person?.source === 'pco' ? 'pco' : 'local',
     pcoPersonId: typeof person?.pcoPersonId === 'string' ? person.pcoPersonId : '',
     pcoPlanPersonId: typeof person?.pcoPlanPersonId === 'string' ? person.pcoPlanPersonId : '',
+    // "MM-DD" only — we deliberately never persist the birth year (month + day is all
+    // Birthday Mode needs, and it keeps a volunteer's age off this machine). '' = none on file.
+    birthday: normalizeBirthdayMmdd(person?.birthday),
   };
 }
 
+/** Coerce a Planning Center birthdate ("YYYY-MM-DD", or an already-trimmed "MM-DD") to "MM-DD", or '' if absent/invalid. */
+function normalizeBirthdayMmdd(raw) {
+  const s = String(raw || '').trim();
+  const full = s.match(/^\d{4}-(\d{2})-(\d{2})$/); // PCO People birthdate shape
+  if (full) return `${full[1]}-${full[2]}`;
+  const md = s.match(/^(\d{2})-(\d{2})$/);
+  if (md) {
+    const mm = Number(md[1]);
+    const dd = Number(md[2]);
+    if (mm >= 1 && mm <= 12 && dd >= 1 && dd <= 31) return `${md[1]}-${md[2]}`;
+  }
+  return '';
+}
+
 function normalizeTeamName(value) {
   return String(value || '').trim().toLowerCase();
 }
@@ -627,6 +694,20 @@ async function syncUpcomingPcoPlan(payload) {
     return a.displayName.localeCompare(b.displayName, undefined, { sensitivity: 'base' });
   });
 
+  // Pull each scheduled person's birthday from the People API (best-effort: a blocked token or a
+  // person with no date on file just yields '' and never fails the sync). Fetched once per unique
+  // person so a member in two positions isn't queried twice.
+  const birthdayByPerson = new Map();
+  for (const member of scheduledMembers) {
+    if (!member.personId || birthdayByPerson.has(member.personId)) continue;
+    try {
+      const { birthday } = await pcoFetchBirthday(member.personId, credentials);
+      birthdayByPerson.set(member.personId, birthday || '');
+    } catch {
+      birthdayByPerson.set(member.personId, '');
+    }
+  }
+
   const oldPcoFiles = new Set(
     (Array.isArray(baseState.library) ? baseState.library : [])
       .filter((entry) => entry?.source === 'pco' && typeof entry?.fileName === 'string')
@@ -652,6 +733,7 @@ async function syncUpcomingPcoPlan(payload) {
       source: 'pco',
       pcoPersonId: member.personId,
       pcoPlanPersonId: member.planPersonId,
+      birthday: birthdayByPerson.get(member.personId) || '',
     });
   }
 
@@ -731,6 +813,7 @@ async function syncUpcomingPcoPlan(payload) {
   const atWriteTime = await loadStateRaw();
   nextState.proPresenter = normalizeProPresenterConfig(atWriteTime.proPresenter);
   nextState.displayServer = normalizeDisplayServerConfig(atWriteTime.displayServer);
+  nextState.birthdayMode = normalizeBirthdayMode(atWriteTime.birthdayMode);
   await saveStateRaw(nextState);
 
   for (const fileName of oldPcoFiles) {
@@ -1222,6 +1305,7 @@ function migrateState(data) {
       pcoDisplayPositions: normalizePcoDisplayPositions(data.pcoDisplayPositions),
       proPresenter: normalizeProPresenterConfig(data.proPresenter),
       displayServer: normalizeDisplayServerConfig(data.displayServer),
+      birthdayMode: normalizeBirthdayMode(data.birthdayMode),
       lineup: data.lineup.map((e) => {
         if (!e || typeof e !== 'object') return { personId: '', label: '' };
         return {
@@ -1432,7 +1516,10 @@ ipcMain.handle('save-state', async (_e, payload) => {
   // The renderer never edits this (it is changed through the display-* IPC handlers), so
   // always carry the stored value forward rather than letting a save blank it out.
   const displayServer = normalizeDisplayServerConfig(existing.displayServer);
-  await saveStateRaw({ library, layout, parallaxEnabled, slotLabels, slotNames, lineup, pcoServiceTypeId, pcoDisplayPositions, proPresenter, displayServer });
+  const birthdayMode = payload?.birthdayMode
+    ? normalizeBirthdayMode(payload.birthdayMode)
+    : normalizeBirthdayMode(existing.birthdayMode);
+  await saveStateRaw({ library, layout, parallaxEnabled, slotLabels, slotNames, lineup, pcoServiceTypeId, pcoDisplayPositions, proPresenter, displayServer, birthdayMode });
   return true;
 });
 
@@ -1511,6 +1598,85 @@ ipcMain.handle('pco-sync-upcoming-plan', async (_e, payload) => {
   return syncUpcomingPcoPlan(payload);
 });
 
+/**
+ * Diagnostic behind the "Test Birthdays" button: does this Personal Access Token actually reach the
+ * People API and read birthdates, and how many synced band members have one on file. Read-only.
+ */
+ipcMain.handle('pco-test-birthdays', async () => {
+  const credentials = await loadPcoCredentials();
+  if (!credentials) return { connected: false };
+
+  // 1. Can the token read the People API at all?
+  let probe;
+  try {
+    probe = await pcoFetchStatus('/people/v2/people', credentials, { per_page: 1, 'fields[Person]': 'birthdate' });
+  } catch (err) {
+    return { connected: true, canRead: false, reason: 'network', detail: err instanceof Error ? err.message : String(err) };
+  }
+  if (!probe.ok) {
+    const detail =
+      probe.payload?.errors?.map((e) => e.detail || e.title).filter(Boolean).join(' | ') ||
+      `${probe.status}`;
+    return { connected: true, canRead: false, status: probe.status, detail };
+  }
+  const sampleAttrs = probe.payload?.data?.[0]?.attributes || null;
+  const fieldExposed = sampleAttrs ? 'birthdate' in sampleAttrs : true;
+
+  // 2. Coverage across the people we've actually synced (unique by person id).
+  const state = await loadStateRaw();
+  const seen = new Set();
+  const targets = [];
+  for (const p of Array.isArray(state.library) ? state.library : []) {
+    if (p?.source !== 'pco' || !p?.pcoPersonId || seen.has(p.pcoPersonId)) continue;
+    seen.add(p.pcoPersonId);
+    targets.push(p);
+  }
+
+  let withBirthday = 0;
+  let notFound = 0;
+  let errors = 0;
+  const found = [];
+  for (const p of targets) {
+    let r;
+    try {
+      r = await pcoFetchBirthday(p.pcoPersonId, credentials);
+    } catch {
+      errors += 1;
+      continue;
+    }
+    if (r.status === 404) { notFound += 1; continue; }
+    if (r.status && r.status >= 400) { errors += 1; continue; }
+    if (r.birthday) {
+      withBirthday += 1;
+      found.push({ name: String(p.lastName || p.originalName || 'Unknown').trim() || 'Unknown', mmdd: r.birthday });
+    }
+  }
+
+  // Soonest upcoming birthday, for a concrete "it works" line.
+  const today = new Date();
+  const daysUntil = (mmdd) => {
+    const [mm, dd] = mmdd.split('-').map(Number);
+    let next = new Date(today.getFullYear(), mm - 1, dd);
+    const midnight = new Date(today.getFullYear(), today.getMonth(), today.getDate());
+    if (next < midnight) next = new Date(today.getFullYear() + 1, mm - 1, dd);
+    return Math.round((next - midnight) / 86400000);
+  };
+  const sortedFound = [...found].sort((a, b) => daysUntil(a.mmdd) - daysUntil(b.mmdd));
+  const nextUp = sortedFound[0] ? { ...sortedFound[0], inDays: daysUntil(sortedFound[0].mmdd) } : null;
+
+  return {
+    connected: true,
+    canRead: true,
+    fieldExposed,
+    total: targets.length,
+    withBirthday,
+    notFound,
+    errors,
+    found: sortedFound.slice(0, 8),
+    nextUp,
+  };
+});
+
 ipcMain.handle('pp-status', async () => {
   return {
     enabled: ppConfig.enabled,

band-lineup-display/package.json

@@ -1,8 +1,8 @@
 {
   "name": "band-lineup-display",
   "productName": "Band Lineup",
-  "version": "1.3.6",
-  "buildNumber": "92",
+  "version": "1.3.10",
+  "buildNumber": "96",
   "description": "Stage lineup photos with mic/pack labels",
   "main": "main.js",
   "scripts": {

band-lineup-display/preload.js

@@ -14,6 +14,7 @@ contextBridge.exposeInMainWorld('lineup', {
   pcoServiceTypes: () => ipcRenderer.invoke('pco-service-types'),
   pcoPositionOptions: (serviceTypeId) => ipcRenderer.invoke('pco-position-options', serviceTypeId),
   pcoSyncUpcomingPlan: (payload) => ipcRenderer.invoke('pco-sync-upcoming-plan', payload),
+  pcoTestBirthdays: () => ipcRenderer.invoke('pco-test-birthdays'),
   onMenuAddPhotos: (cb) => {
     ipcRenderer.on('menu-add-photos', () => cb());
   },

band-lineup-display/renderer.js

@@ -3,7 +3,7 @@ if (window.__bandLineupRendererLoaded) {
 } else {
   window.__bandLineupRendererLoaded = true;
 /**
- * @typedef {{ id: string, fileName: string, originalName: string, lastLabel: string, lastName: string, source?: string, pcoPersonId?: string, pcoPlanPersonId?: string }} LibraryPerson
+ * @typedef {{ id: string, fileName: string, originalName: string, lastLabel: string, lastName: string, source?: string, pcoPersonId?: string, pcoPlanPersonId?: string, birthday?: string }} LibraryPerson
  * @typedef {{ personId: string, label: string }} StageSlot
  * @typedef {{ teamName: string, positionName: string, count: number }} PcoDisplayPosition
  */
@@ -27,6 +27,10 @@ let pcoDisplayPositions = [];
 let pcoPositionOptions = [];
 let slotLabelMemory = [];
 let slotNameMemory = [];
+/** Birthday Mode display settings (persisted). */
+let birthdayMode = { enabled: true, intensity: 'subtle' };
+/** Person id forced into Birthday Mode for testing — in-memory only, never saved, clears on restart. */
+let birthdayTestPersonId = '';
 /** @type {StageSlot[]} */
 let stageSlots = createEmptySlots();
 const imageUrlCache = new Map();
@@ -65,7 +69,13 @@ const btnApplyLayout = document.getElementById('btn-apply-layout');
 const btnToggleParallax = document.getElementById('btn-toggle-parallax');
 const btnPcoConnect = document.getElementById('btn-pco-connect');
 const btnPcoSync = document.getElementById('btn-pco-sync');
+const btnPcoTestBirthdays = document.getElementById('btn-pco-test-birthdays');
 const btnPcoDisconnect = document.getElementById('btn-pco-disconnect');
+const pcoBirthdayResult = document.getElementById('pco-birthday-result');
+const bdayEnabled = document.getElementById('bday-enabled');
+const bdayIntensity = document.getElementById('bday-intensity');
+const bdayControls = document.getElementById('bday-controls');
+const bdayTestSelect = document.getElementById('bday-test');
 const btnPcoAddPosition = document.getElementById('btn-pco-add-position');
 const inputLayoutCols = document.getElementById('layout-cols');
 const inputLayoutRows = document.getElementById('layout-rows');
@@ -244,6 +254,7 @@ function setPcoStatus(message, isError = false) {
 function setPcoControlsEnabled(enabled) {
   btnPcoConnect.disabled = !enabled;
   btnPcoSync.disabled = !enabled;
+  btnPcoTestBirthdays.disabled = !enabled;
   btnPcoDisconnect.disabled = !enabled;
   btnPcoAddPosition.disabled = !enabled;
   pcoServiceTypeSelect.disabled = !enabled;
@@ -427,6 +438,9 @@ function applyLoadedState(data) {
         source: person?.source === 'pco' ? 'pco' : 'local',
         pcoPersonId: typeof person?.pcoPersonId === 'string' ? person.pcoPersonId : '',
         pcoPlanPersonId: typeof person?.pcoPlanPersonId === 'string' ? person.pcoPlanPersonId : '',
+        // Carried through so a routine save doesn't wipe birthdays a PCO sync stored (main.js
+        // re-validates the "MM-DD" shape on write); Birthday Mode reads this.
+        birthday: typeof person?.birthday === 'string' ? person.birthday : '',
       }))
     : [];
   const savedColumns = Number.parseInt(String(data?.layout?.columns ?? DEFAULT_COLUMNS), 10);
@@ -451,6 +465,11 @@ function applyLoadedState(data) {
   pcoServiceTypeSelect.value = pcoServiceTypeId;
   renderPcoDisplayPositions();
   stageSlots = normalizeLineup(data.lineup, getStageSlotCount());
+  birthdayMode = {
+    enabled: data?.birthdayMode?.enabled === undefined ? true : Boolean(data.birthdayMode.enabled),
+    intensity: data?.birthdayMode?.intensity === 'full' ? 'full' : 'subtle',
+  };
+  syncBirthdayControls();
 }
 
 function updateSlotSizeReadout() {
@@ -528,6 +547,7 @@ function scheduleSave() {
       slotLabels: slotLabelMemory,
       slotNames: slotNameMemory,
       lineup: stageSlots,
+      birthdayMode,
     });
   }, 250);
 }
@@ -950,6 +970,132 @@ function parallaxMotionVars(seedText) {
   };
 }
 
+/* ---------------- Birthday Mode ---------------- */
+
+const BIRTHDAY_COLORS = ['#f5c451', '#ff6b81', '#4fd1c5', '#a78bfa', '#ffffff'];
+/** Live confetti canvases; a single rAF loop drives them and prunes any whose tile was rebuilt. */
+const birthdayCanvases = new Set();
+let birthdayRaf = null;
+
+/**
+ * The 7 "MM-DD" dates of the current celebration week, which runs Wednesday→Tuesday. A birthday
+ * anywhere in this window celebrates all week (so it's already up for the weekend services).
+ * Cached per week; birthdayTick() re-renders the stage when the window rolls over to a new Wednesday.
+ */
+let birthdayWeekCache = { key: '', set: null };
+function birthdayWeekSet() {
+  const now = new Date();
+  const daysSinceWed = (now.getDay() - 3 + 7) % 7; // getDay: Sun=0…Wed=3…Sat=6
+  const start = new Date(now.getFullYear(), now.getMonth(), now.getDate() - daysSinceWed);
+  const key = `${start.getFullYear()}-${start.getMonth()}-${start.getDate()}`;
+  if (birthdayWeekCache.key === key && birthdayWeekCache.set) return birthdayWeekCache.set;
+  const set = new Set();
+  for (let i = 0; i < 7; i += 1) {
+    const d = new Date(start.getFullYear(), start.getMonth(), start.getDate() + i);
+    set.add(`${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`);
+  }
+  birthdayWeekCache = { key, set };
+  return set;
+}
+
+/** Is this person celebrating this week — their birthday falls in the current Wed→Tue window, or they're the test override. */
+function isBirthdayActive(person) {
+  if (!birthdayMode.enabled || !person) return false;
+  if (birthdayTestPersonId && person.id === birthdayTestPersonId) return true;
+  return typeof person.birthday === 'string' && person.birthday.length === 5 && birthdayWeekSet().has(person.birthday);
+}
+
+/** Re-render the stage when the celebration week rolls over (the app can stay open for days). */
+function birthdayTick() {
+  const before = birthdayWeekCache.key;
+  birthdayWeekSet();
+  if (before && birthdayWeekCache.key !== before) void renderStage();
+}
+setInterval(birthdayTick, 15 * 60 * 1000);
+
+function birthdayMakeParticle(w, h, intensity, seedY) {
+  const ribbon = Math.random() < 0.55;
+  return {
+    x: Math.random() * w,
+    y: seedY != null ? seedY : Math.random() * h,
+    w: ribbon ? 4 + Math.random() * 4 : 5 + Math.random() * 5,
+    h: ribbon ? 9 + Math.random() * 8 : 0,
+    ribbon,
+    color: BIRTHDAY_COLORS[(Math.random() * BIRTHDAY_COLORS.length) | 0],
+    rot: Math.random() * Math.PI * 2,
+    vr: -0.14 + Math.random() * 0.28,
+    sway: 0.6 + Math.random() * 1.1,
+    phase: Math.random() * Math.PI * 2,
+    vy: (intensity === 'subtle' ? 0.6 : 1.0) * (1.1 + Math.random() * 1.5),
+  };
+}
+
+function birthdaySeedCanvas(c, w, h) {
+  const base = c._intensity === 'subtle' ? 26 : 64;
+  const count = Math.max(10, Math.round((base * (w * h)) / (300 * 500)));
+  c._parts = Array.from({ length: count }, () => birthdayMakeParticle(w, h, c._intensity));
+}
+
+// The confetti ALWAYS animates — this is a celebration effect, so it intentionally ignores the
+// OS "reduced motion" setting (which was freezing the confetti mid-fall on the backstage machine).
+function birthdayStepCanvas(c) {
+  const w = c.clientWidth;
+  const h = c.clientHeight;
+  if (!w || !h) return; // not laid out yet — try again next frame
+  const dpr = Math.min(window.devicePixelRatio || 1, 2);
+  if (c._w !== w || c._h !== h) {
+    c.width = w * dpr;
+    c.height = h * dpr;
+    c._ctx = c.getContext('2d');
+    c._ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    c._w = w;
+    c._h = h;
+    birthdaySeedCanvas(c, w, h);
+  }
+  const ctx = c._ctx;
+  ctx.clearRect(0, 0, w, h);
+  for (const p of c._parts) {
+    p.phase += 0.03;
+    p.y += p.vy;
+    p.x += Math.sin(p.phase) * p.sway;
+    p.rot += p.vr;
+    if (p.y > h + 16) Object.assign(p, birthdayMakeParticle(w, h, c._intensity, -16));
+    ctx.save();
+    ctx.translate(p.x, p.y);
+    ctx.rotate(p.rot);
+    ctx.fillStyle = p.color;
+    if (p.ribbon) ctx.fillRect(-p.w / 2, -p.h / 2, p.w, p.h);
+    else { ctx.beginPath(); ctx.arc(0, 0, p.w / 2, 0, Math.PI * 2); ctx.fill(); }
+    ctx.restore();
+  }
+}
+
+function birthdayLoop() {
+  for (const c of [...birthdayCanvases]) {
+    if (!c.isConnected) { birthdayCanvases.delete(c); continue; }
+    birthdayStepCanvas(c);
+  }
+  birthdayRaf = birthdayCanvases.size ? window.requestAnimationFrame(birthdayLoop) : null;
+}
+
+function birthdayRegisterCanvas(canvas, intensity) {
+  canvas._intensity = intensity;
+  birthdayCanvases.add(canvas);
+  if (!birthdayRaf) birthdayRaf = window.requestAnimationFrame(birthdayLoop);
+}
+
+/** Rain confetti (plus a soft gold glow) onto a tile whose person is celebrating. */
+function applyBirthdayEffects(tile, photoArea) {
+  const intensity = birthdayMode.intensity === 'full' ? 'full' : 'subtle';
+  tile.classList.add('birthday', `birthday-${intensity}`);
+
+  const confetti = document.createElement('canvas');
+  confetti.className = 'birthday-confetti';
+  confetti.setAttribute('aria-hidden', 'true');
+  photoArea.appendChild(confetti);
+  birthdayRegisterCanvas(confetti, intensity);
+}
+
 function createPhotoTile(person, href, slotIndex, parallaxAssets) {
   void parallaxAssets;
   const tile = document.createElement('article');
@@ -1002,6 +1148,7 @@ function createPhotoTile(person, href, slotIndex, parallaxAssets) {
 
   photoArea.appendChild(nameBadge);
   photoArea.appendChild(removeBtn);
+  if (isBirthdayActive(person)) applyBirthdayEffects(tile, photoArea);
   tile.appendChild(photoArea);
   return tile;
 }
@@ -1156,6 +1303,7 @@ async function renderLibrary() {
 async function renderAll() {
   await renderStage();
   await renderLibrary();
+  renderBirthdayTestOptions();
 }
 
 async function importNewPeople(added) {
@@ -1170,6 +1318,7 @@ async function importNewPeople(added) {
       source: 'local',
       pcoPersonId: '',
       pcoPlanPersonId: '',
+      birthday: '',
     });
   }
   await renderLibrary();
@@ -1232,6 +1381,97 @@ async function syncUpcomingPlanFromPco() {
   }
 }
 
+const BIRTHDAY_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+function formatBirthdayMmdd(mmdd) {
+  const parts = String(mmdd || '').split('-');
+  const mm = Number(parts[0]);
+  const dd = Number(parts[1]);
+  if (!(mm >= 1 && mm <= 12) || !(dd >= 1 && dd <= 31)) return '';
+  return `${BIRTHDAY_MONTHS[mm - 1]} ${dd}`;
+}
+
+function setPcoBirthdayResult(message, tone) {
+  if (!pcoBirthdayResult) return;
+  pcoBirthdayResult.textContent = message || '';
+  pcoBirthdayResult.style.display = message ? '' : 'none';
+  pcoBirthdayResult.style.color = tone === 'error' ? '#ffb1b1' : tone === 'good' ? '#8fe0b0' : '#9ea7bc';
+}
+
+async function testPcoBirthdays() {
+  setPcoControlsEnabled(false);
+  setPcoBirthdayResult('Checking Planning Center for birthday access…', 'info');
+  try {
+    const r = await window.lineup.pcoTestBirthdays();
+    if (!r || r.connected === false) {
+      setPcoBirthdayResult('Connect Planning Center first, then test birthday access.', 'error');
+      return;
+    }
+    if (!r.canRead) {
+      const why = r.reason === 'network'
+        ? `Couldn't reach Planning Center (${r.detail || 'network error'}).`
+        : `This token can't read People birthdays${r.status ? ` (HTTP ${r.status})` : ''}${r.detail ? ` — ${r.detail}` : ''}.`;
+      setPcoBirthdayResult(`✕ ${why} Birthday Mode needs People access on the token.`, 'error');
+      return;
+    }
+    // Access works. Report coverage across synced band members.
+    if (r.total === 0) {
+      setPcoBirthdayResult('✓ People access works. Sync an upcoming plan, then test again to see how many musicians have a birthday on file.', 'good');
+      return;
+    }
+    const bits = [`✓ People access works — ${r.withBirthday} of ${r.total} synced ${r.total === 1 ? 'person has' : 'people have'} a birthday on file.`];
+    if (r.nextUp) {
+      const when = r.nextUp.inDays === 0 ? 'today 🎂' : r.nextUp.inDays === 1 ? 'tomorrow' : `in ${r.nextUp.inDays} days`;
+      bits.push(`Next up: ${r.nextUp.name} (${formatBirthdayMmdd(r.nextUp.mmdd)}, ${when}).`);
+    }
+    if (r.notFound) bits.push(`${r.notFound} not matched in People.`);
+    setPcoBirthdayResult(bits.join(' '), r.withBirthday > 0 ? 'good' : 'info');
+  } catch (error) {
+    setPcoBirthdayResult(error instanceof Error ? error.message : 'Birthday test failed.', 'error');
+  } finally {
+    setPcoControlsEnabled(true);
+  }
+}
+
+/* ---------------- Birthday Mode controls ---------------- */
+
+/** Reflect current birthdayMode settings onto the controls (called after load). */
+function syncBirthdayControls() {
+  if (bdayEnabled) bdayEnabled.checked = birthdayMode.enabled;
+  if (bdayIntensity) {
+    for (const b of bdayIntensity.querySelectorAll('button')) {
+      b.setAttribute('aria-pressed', b.dataset.int === birthdayMode.intensity ? 'true' : 'false');
+    }
+  }
+  if (bdayControls) bdayControls.style.opacity = birthdayMode.enabled ? '' : '0.45';
+}
+
+/** Rebuild the "Force on (test)" dropdown from whoever is currently on the stage. */
+function renderBirthdayTestOptions() {
+  if (!bdayTestSelect) return;
+  const previous = birthdayTestPersonId;
+  bdayTestSelect.innerHTML = '<option value="">Off</option>';
+  const seen = new Set();
+  stageSlots.forEach((slot, index) => {
+    if (!slot.personId || seen.has(slot.personId)) return;
+    const person = getPerson(slot.personId);
+    if (!person) return;
+    seen.add(slot.personId);
+    const option = document.createElement('option');
+    option.value = person.id;
+    const name = String(getStageName(index, person) || person.lastName || 'Unknown').trim();
+    const label = String(slotLabelMemory[index] || '').trim();
+    option.textContent = label ? `${name} — ${label}` : name;
+    bdayTestSelect.appendChild(option);
+  });
+  // Keep the current override selected if that person is still on stage; otherwise drop it.
+  if (previous && seen.has(previous)) {
+    bdayTestSelect.value = previous;
+  } else if (previous) {
+    birthdayTestPersonId = '';
+    bdayTestSelect.value = '';
+  }
+}
+
 /* ---------------- Setup panel tabs ---------------- */
 
 /** Set while a tab switch blurs the port field, so the blur handler doesn't commit. */
@@ -1257,6 +1497,7 @@ function activatePanelTab(name) {
   }
   // The readout measures a stage slot, so it can only be filled in once its pane is laid out.
   if (name === 'pictures') window.requestAnimationFrame(updateSlotSizeReadout);
+  if (name === 'pco') renderBirthdayTestOptions();
 }
 
 /* ---------------- Studio displays (hosting the Now/Next page on the LAN) ---------------- */
@@ -1733,6 +1974,36 @@ btnPcoSync.addEventListener('click', () => {
   void syncUpcomingPlanFromPco();
 });
 
+btnPcoTestBirthdays.addEventListener('click', () => {
+  revealChrome();
+  void testPcoBirthdays();
+});
+
+if (bdayEnabled) {
+  bdayEnabled.addEventListener('change', () => {
+    birthdayMode.enabled = bdayEnabled.checked;
+    syncBirthdayControls();
+    scheduleSave();
+    void renderStage();
+  });
+}
+if (bdayIntensity) {
+  bdayIntensity.addEventListener('click', (e) => {
+    const btn = e.target.closest('button[data-int]');
+    if (!btn) return;
+    birthdayMode.intensity = btn.dataset.int === 'full' ? 'full' : 'subtle';
+    syncBirthdayControls();
+    scheduleSave();
+    void renderStage();
+  });
+}
+if (bdayTestSelect) {
+  bdayTestSelect.addEventListener('change', () => {
+    birthdayTestPersonId = bdayTestSelect.value || '';
+    void renderStage();
+  });
+}
+
 btnPcoDisconnect.addEventListener('click', async () => {
   revealChrome();
   setPcoControlsEnabled(false);
@@ -1744,6 +2015,7 @@ btnPcoDisconnect.addEventListener('click', async () => {
     renderPcoPositionOptions();
     scheduleSave();
     setPcoStatus('Planning Center disconnected.');
+    setPcoBirthdayResult('');
   } catch (error) {
     setPcoStatus(error instanceof Error ? error.message : 'Could not disconnect Planning Center.', true);
   } finally {

band-lineup-display/styles.css

@@ -331,6 +331,105 @@ body {
   color: #9ea7bc;
 }
 
+.pco-birthday-result {
+  min-height: 0;
+  line-height: 1.45;
+}
+
+.pco-birthday-result:empty {
+  display: none;
+}
+
+/* ---- Birthday Mode settings ---- */
+.bday-block {
+  margin-top: 14px;
+  border-top: 1px solid #23232c;
+  padding-top: 12px;
+}
+.bday-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+.bday-title {
+  font-size: 13px;
+  font-weight: 700;
+  color: #e7e7ef;
+}
+.bday-switch {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  cursor: pointer;
+  font-size: 12px;
+  color: #9ea7bc;
+}
+.bday-controls {
+  margin-top: 10px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.bday-line {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.bday-line-label {
+  font-size: 11px;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: #8a8a99;
+  min-width: 74px;
+}
+.bday-line-label em {
+  font-style: normal;
+  text-transform: none;
+  letter-spacing: 0;
+  color: #6d6d7a;
+}
+.seg-inline {
+  display: inline-flex;
+  gap: 4px;
+  background: #0e0e14;
+  border: 1px solid #23232c;
+  border-radius: 9px;
+  padding: 3px;
+}
+.seg-inline button {
+  appearance: none;
+  border: 0;
+  background: transparent;
+  color: #9ea7bc;
+  font: inherit;
+  font-size: 12px;
+  font-weight: 600;
+  padding: 5px 12px;
+  border-radius: 6px;
+  cursor: pointer;
+}
+.seg-inline button[aria-pressed="true"] {
+  background: #f5c451;
+  color: #241a02;
+}
+.bday-check {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-size: 12px;
+  color: #c6cada;
+  cursor: pointer;
+}
+.bday-test-select {
+  flex: 1;
+  min-width: 150px;
+}
+.bday-hint {
+  font-size: 11px;
+  color: #6d6d7a;
+}
+
 .pco-position-builder {
   display: none;
   grid-template-columns: minmax(0, 1fr) auto;
@@ -624,6 +723,33 @@ body {
   font-weight: 500;
 }
 
+/* ---- Birthday Mode tile effects ---- */
+.tile.birthday-subtle {
+  animation: bdayGlowSubtle 3.4s ease-in-out infinite;
+}
+.tile.birthday-full {
+  animation: bdayGlowFull 2.2s ease-in-out infinite;
+}
+@keyframes bdayGlowSubtle {
+  0%, 100% { box-shadow: inset 0 0 0 2px rgba(245, 196, 81, 0.55), 0 0 14px rgba(245, 196, 81, 0.18); }
+  50% { box-shadow: inset 0 0 0 2px rgba(245, 196, 81, 0.85), 0 0 20px rgba(245, 196, 81, 0.32); }
+}
+@keyframes bdayGlowFull {
+  0%, 100% { box-shadow: inset 0 0 0 3px rgba(245, 196, 81, 0.8), 0 0 20px rgba(245, 196, 81, 0.42); }
+  50% { box-shadow: inset 0 0 0 3px #ffd873, 0 0 34px rgba(245, 196, 81, 0.66); }
+}
+
+/* Birthday Mode intentionally keeps animating even under OS "reduced motion" — it's a celebration
+   the operator opts into, and freezing it leaves confetti stuck mid-fall. */
+
+.birthday-confetti {
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  pointer-events: none;
+}
+
+
 .tile .remove {
   position: absolute;
   top: 6px;

docs/MODULE-GUIDE.md

@@ -136,7 +136,7 @@ the app); its settings are kept for a later reinstall.
 | `client` | yes | Client entry file, loaded as an ES module. |
 | `server` | no | Server entry file (CommonJS), loaded with `require()`. |
 | `style` | no | A stylesheet the shell injects once per module. |
-| `minSize`, `defaultSize` | no | Tile size in grid cells (12 columns wide; rows are ~72 px). Defaults: min 1×1, default 4×3. |
+| `minSize`, `defaultSize` | no | Tile size in grid cells, declared for the default grid (12 columns, 72 px rows). Defaults: min 1×1, default 4×3. A dashboard may cut its board finer or coarser (8–24 columns, from the Layouts menu; row height follows). `defaultSize` is scaled to that density when a tile is added, so a new tile lands at about the size you meant; `minSize` is enforced in cells as declared, so on a finer grid a tile can be made smaller than it could at 12. |
 | `configSchema` | no | **Admin config** — server-wide settings (URLs, ports, keys) edited once at `/admin` for everyone. |
 | `instanceSchema` | no | **Per-tile settings** — chosen in each tile's gear menu and stored with that browser's layout (filters, text sizes, display options). They apply as they are changed, so keep them to display choices. |
 | `tiles` | no | Fixed multi-tile list for client-only modules; server modules export a dynamic `tiles()` instead. See **Presenting multiple tiles**. |
@@ -592,10 +592,17 @@ module.exports = {
 - When the user adds an entry, its `settings` overlay your `instanceSchema`
   defaults in that tile's instance settings, the entry's `name` becomes the
   tile's title, and `moduleApi.variant` carries its `id`.
-- The tile keeps its variant id and title even if the entry later vanishes
-  from your list (a timer deleted in ProPresenter, a page removed in admin).
-  **Your client decides what that means** — show a clear "no longer
-  configured" state rather than erroring.
+- **A tile is shown only while its entry is offered.** The shell mounts a
+  tile added from an entry only when that entry (or one of its `aliases`) is
+  in your list right now; otherwise the tile keeps its place in the layout,
+  draws nothing, and appears the moment your list offers it again — a
+  Service timer waits for PCO Plan, a transcript for its channel. So your
+  client is never asked to render an entry you did not offer at mount time.
+  One case is still yours: an entry that vanishes *after* the tile mounted
+  (a timer deleted in ProPresenter mid-service). Render nothing for it — no
+  placeholder, no error — and the shell folds the tile away at its next
+  registry refresh. Never fall back to your default view in its place: five
+  different timers turning into five "All timers" is worse than five gaps.
 - A client-only module can declare a fixed list as a `tiles` array in
   `module.json` instead (same entry shape).
 - An empty list (or no `tiles` at all) keeps today's behavior: one picker

modules/band-lineup/client.js

@@ -0,0 +1,299 @@
+// Band Lineup — client. Renders the shared stage board from /state + /stream.
+// The Edit button opens an editor: an uploaded-photo library you drag (or click)
+// into slots, plus rename / clear / upload / delete. Edits go to the server and
+// come back over SSE, so every Band Lineup screen stays in sync. Birthday week
+// (Wed→Tue) rains confetti.
+
+const CONFETTI_COLORS = ['#f5c451', '#ff6b81', '#4fd1c5', '#a78bfa', '#ffffff'];
+
+export default function create({ root, moduleApi }) {
+  let stream = null;
+  let state = null;
+  let editing = false;
+  let choirBtn = null;
+  let selectedLibId = ''; // click-to-place fallback for touch
+  const canvases = new Set();
+  let raf = null;
+  // Auto-scroll the editor while dragging a photo (native DnD won't do it reliably).
+  let dragScrolling = false;
+  let dragY = 0;
+  let dragBody = null;
+  let dragRaf = null;
+  function startDragAutoScroll() {
+    if (dragRaf) return;
+    const tick = () => {
+      if (!dragScrolling || !dragBody || !dragBody.isConnected) { dragRaf = null; return; }
+      const r = dragBody.getBoundingClientRect();
+      const zone = 90; // generous edge band so you don't have to be pixel-accurate
+      let dy = 0;
+      if (dragY < r.top + zone) dy = -Math.ceil((r.top + zone - dragY) / 4) - 3;
+      else if (dragY > r.bottom - zone) dy = Math.ceil((dragY - (r.bottom - zone)) / 4) + 3;
+      if (dy) dragBody.scrollTop += dy;
+      dragRaf = requestAnimationFrame(tick);
+    };
+    dragRaf = requestAnimationFrame(tick);
+  }
+  function stopDragAutoScroll() { dragScrolling = false; if (dragRaf) { cancelAnimationFrame(dragRaf); dragRaf = null; } }
+
+  /* ---------- confetti (always animates) ---------- */
+  function makeParticle(w, h, intensity, seedY) {
+    const ribbon = Math.random() < 0.55;
+    return {
+      x: Math.random() * w, y: seedY != null ? seedY : Math.random() * h,
+      w: ribbon ? 4 + Math.random() * 4 : 5 + Math.random() * 5, h: ribbon ? 9 + Math.random() * 8 : 0, ribbon,
+      color: CONFETTI_COLORS[(Math.random() * CONFETTI_COLORS.length) | 0],
+      rot: Math.random() * Math.PI * 2, vr: -0.14 + Math.random() * 0.28,
+      sway: 0.6 + Math.random() * 1.1, phase: Math.random() * Math.PI * 2,
+      vy: (intensity === 'subtle' ? 0.6 : 1.0) * (1.1 + Math.random() * 1.5),
+    };
+  }
+  function seed(c, w, h) { const base = c._intensity === 'subtle' ? 26 : 64; const n = Math.max(10, Math.round((base * (w * h)) / (300 * 500))); c._parts = Array.from({ length: n }, () => makeParticle(w, h, c._intensity)); }
+  function step(c) {
+    const w = c.clientWidth, h = c.clientHeight; if (!w || !h) return;
+    const dpr = Math.min(window.devicePixelRatio || 1, 2);
+    if (c._w !== w || c._h !== h) { c.width = w * dpr; c.height = h * dpr; c._ctx = c.getContext('2d'); c._ctx.setTransform(dpr, 0, 0, dpr, 0, 0); c._w = w; c._h = h; seed(c, w, h); }
+    const ctx = c._ctx; ctx.clearRect(0, 0, w, h);
+    for (const p of c._parts) {
+      p.phase += 0.03; p.y += p.vy; p.x += Math.sin(p.phase) * p.sway; p.rot += p.vr;
+      if (p.y > h + 16) Object.assign(p, makeParticle(w, h, c._intensity, -16));
+      ctx.save(); ctx.translate(p.x, p.y); ctx.rotate(p.rot); ctx.fillStyle = p.color;
+      if (p.ribbon) ctx.fillRect(-p.w / 2, -p.h / 2, p.w, p.h); else { ctx.beginPath(); ctx.arc(0, 0, p.w / 2, 0, Math.PI * 2); ctx.fill(); }
+      ctx.restore();
+    }
+  }
+  function loop() { for (const c of [...canvases]) { if (!c.isConnected) { canvases.delete(c); continue; } step(c); } raf = canvases.size ? requestAnimationFrame(loop) : null; }
+  function addConfetti(host, intensity) { const c = document.createElement('canvas'); c.className = 'bl-confetti'; c._intensity = intensity; host.appendChild(c); canvases.add(c); if (!raf) raf = requestAnimationFrame(loop); }
+
+  /* ---------- helpers ---------- */
+  function initials(name) { const p = String(name || '').trim().split(/\s+/).filter(Boolean).slice(0, 2); return p.length ? p.map((x) => x[0]).join('').toUpperCase() : ''; }
+  // Per-tile Columns wins; 0 falls back to the admin default.
+  function resolveCols() { const per = Number(moduleApi.instanceSettings.columns) || 0; return Math.max(1, per > 0 ? per : (Number(state && state.columns) || 7)); }
+  function el(tag, cls, text) { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; }
+  function photoNode(person, cls) {
+    if (person && person.photo) { const img = el('img', cls || 'bl-img'); img.alt = ''; img.src = person.photo; img.loading = 'lazy'; return img; }
+    return el('div', 'bl-initials', initials(person && person.name));
+  }
+  async function api(pathStr, opts) { try { return await moduleApi.fetch(pathStr, opts); } catch { return null; } }
+
+  /* ---------- display board ---------- */
+  function stopConfetti() { canvases.clear(); if (raf) { cancelAnimationFrame(raf); raf = null; } }
+
+  function render() {
+    stopConfetti();
+    stopParallax();
+    root.innerHTML = '';
+    if (choirBtn) choirBtn.classList.toggle('active', !!(state && state.choir));
+    if (editing) { renderEditor(); return; }
+
+    const board = el('div', 'bl-board');
+    if (!state) { board.classList.add('bl-message'); board.textContent = 'Connecting…'; root.appendChild(board); return; }
+
+    const s = moduleApi.instanceSettings;
+    const birthdays = s.birthdays !== false;
+    const intensity = s.birthdayIntensity === 'full' ? 'full' : 'subtle';
+    const testIndex = birthdays ? String(s.birthdayTest || '') : '';
+    const cols = resolveCols();
+    const rows = Math.max(1, Math.ceil((state.slots ? state.slots.length : 1) / cols));
+    board.style.setProperty('--bl-cols', cols);
+    board.style.setProperty('--bl-rows', rows);
+
+    for (const slot of state.slots || []) {
+      const cell = el('div', 'bl-slot');
+      const person = slot.person;
+      if (person) {
+        const tile = el('div', 'bl-tile');
+        const photo = el('div', 'bl-photo');
+        photo.appendChild(photoNode(person));
+        const celebrating = birthdays && (person.celebrating || (testIndex !== '' && testIndex === String(slot.index)));
+        if (celebrating) { tile.classList.add('bl-birthday', `bl-birthday-${intensity}`); addConfetti(photo, intensity); }
+        if (s.showNames !== false && person.name) photo.appendChild(el('div', 'bl-name', person.name));
+        tile.appendChild(photo);
+        if (s.showLabels !== false && slot.label) tile.appendChild(el('div', 'bl-label', slot.label));
+        cell.appendChild(tile);
+      } else {
+        const empty = el('div', 'bl-tile bl-empty');
+        empty.appendChild(el('div', 'bl-label bl-label-empty', slot.label || `Slot ${slot.index + 1}`));
+        cell.appendChild(empty);
+      }
+      board.appendChild(cell);
+    }
+    root.appendChild(board);
+    applyParallax(board, s.parallax !== false);
+    reportStatus();
+  }
+
+  /* ---------- parallax: each photo drifts on its own, automatically ---------- */
+  let parallaxRaf = null;
+  let parallaxImgs = [];
+  function stopParallax() { if (parallaxRaf) { cancelAnimationFrame(parallaxRaf); parallaxRaf = null; } parallaxImgs = []; }
+  function applyParallax(board, on) {
+    stopParallax();
+    const imgs = [...board.querySelectorAll('.bl-img')];
+    if (!on) { imgs.forEach((i) => { i.style.transform = ''; }); return; }
+    // Give each image its own gentle, endless drift — different amplitude, speed and phase,
+    // so the wall never looks frozen and no two photos move together. No mouse needed.
+    parallaxImgs = imgs.map((img) => ({
+      img,
+      ax: 4 + Math.random() * 5, ay: 4 + Math.random() * 5,
+      // Very slow: a full drift cycle takes roughly a minute, so the motion only
+      // registers if you actually watch for it.
+      sx: 0.03 + Math.random() * 0.05, sy: 0.03 + Math.random() * 0.05,
+      px: Math.random() * Math.PI * 2, py: Math.random() * Math.PI * 2,
+    }));
+    const tick = () => {
+      const t = performance.now() / 1000;
+      for (const p of parallaxImgs) {
+        if (!p.img.isConnected) continue;
+        p.img.style.transform = `scale(1.08) translate(${(Math.sin(t * p.sx + p.px) * p.ax).toFixed(2)}px, ${(Math.cos(t * p.sy + p.py) * p.ay).toFixed(2)}px)`;
+      }
+      parallaxRaf = requestAnimationFrame(tick);
+    };
+    parallaxRaf = requestAnimationFrame(tick);
+  }
+
+  function reportStatus() {
+    if (!state) return moduleApi.setStatus('connecting', 'Connecting…');
+    if (state.configured && !state.reachable) return moduleApi.setStatus('error', state.lastError || 'Planning Center unreachable');
+    return moduleApi.setStatus('ok', state.plan?.dates ? `Plan: ${state.plan.dates}` : 'Ready');
+  }
+
+  /* ---------- editor ---------- */
+  function renderEditor() {
+    // No top bar: the photo source is managed in Admin (Google Drive link). Edit mode is just the
+    // board on top and the picture picker (library) below it.
+    const wrap = el('div', 'bl-editor bl-editor-nobar');
+    const body = el('div', 'bl-editor-body');
+    // Feed the drag auto-scroller the pointer position anywhere over the editor.
+    body.addEventListener('dragover', (e) => { dragY = e.clientY; });
+
+    // Slots (drop targets)
+    const boardEl = el('div', 'bl-edit-board');
+    boardEl.style.setProperty('--bl-cols', resolveCols());
+    for (const slot of state?.slots || []) {
+      const cell = el('div', 'bl-edit-slot');
+      cell.dataset.index = String(slot.index);
+      const photo = el('div', 'bl-edit-photo');
+      photo.appendChild(slot.person ? photoNode(slot.person) : el('div', 'bl-edit-drop', '＋'));
+      cell.appendChild(photo);
+      // An occupied card is a drag SOURCE too — move/swap it to another slot.
+      if (slot.person) {
+        cell.draggable = true;
+        cell.addEventListener('dragstart', (e) => {
+          e.dataTransfer.setData('text/plain', 'slot:' + slot.index); e.dataTransfer.effectAllowed = 'move';
+          dragBody = body; dragScrolling = true; startDragAutoScroll();
+        });
+        cell.addEventListener('dragend', stopDragAutoScroll);
+      }
+      const nameRow = el('div', 'bl-edit-namerow');
+      const nameBtn = el('button', 'bl-edit-name', (slot.person && slot.person.name) || 'Name…');
+      nameBtn.addEventListener('click', () => renameSlot(slot.index, slot.person ? slot.person.name : ''));
+      nameRow.appendChild(nameBtn);
+      if (slot.person) { const clr = el('button', 'bl-edit-clear', '×'); clr.title = 'Clear'; clr.addEventListener('click', () => api(`/slot/${slot.index}/clear`, { method: 'POST' })); nameRow.appendChild(clr); }
+      cell.appendChild(nameRow);
+      cell.appendChild(el('div', 'bl-edit-label', slot.label || `Slot ${slot.index + 1}`));
+      // drop
+      cell.addEventListener('dragover', (e) => { e.preventDefault(); cell.classList.add('bl-drop-over'); });
+      cell.addEventListener('dragleave', () => cell.classList.remove('bl-drop-over'));
+      cell.addEventListener('drop', (e) => {
+        e.preventDefault(); stopDragAutoScroll(); cell.classList.remove('bl-drop-over');
+        const data = e.dataTransfer.getData('text/plain') || '';
+        if (data.startsWith('lib:')) assign(slot.index, data.slice(4));
+        else if (data.startsWith('slot:')) { const from = data.slice(5); if (from !== String(slot.index)) api(`/move?from=${from}&to=${slot.index}`, { method: 'POST' }); }
+      });
+      cell.addEventListener('click', (e) => { if (e.target.closest('.bl-edit-name') || e.target.closest('.bl-edit-clear')) return; if (selectedLibId) assign(slot.index, selectedLibId); });
+      boardEl.appendChild(cell);
+    }
+    body.appendChild(boardEl);
+
+    // Library
+    const lib = el('div', 'bl-library');
+    const list = state?.library || [];
+    if (!list.length) lib.appendChild(el('div', 'bl-lib-empty', 'No photos yet — set a Google Drive folder link in Admin, or hit Sync. Then drag a photo onto a slot.'));
+    for (const person of list) {
+      const item = el('div', 'bl-lib-item'); item.draggable = true; item.dataset.id = person.id;
+      if (person.id === selectedLibId) item.classList.add('bl-lib-selected');
+      const ph = el('div', 'bl-lib-photo'); ph.appendChild(photoNode(person, 'bl-lib-img')); item.appendChild(ph);
+      const nm = el('button', 'bl-lib-name', person.name || 'Name…');
+      nm.addEventListener('click', (e) => { e.stopPropagation(); renameLibrary(person.id, person.name); });
+      item.appendChild(nm);
+      const del = el('button', 'bl-lib-del', '×'); del.title = 'Delete photo';
+      del.addEventListener('click', (e) => { e.stopPropagation(); if (confirm(`Delete ${person.name || 'this photo'} from the library?`)) api(`/library/${person.id}/delete`, { method: 'POST' }); });
+      item.appendChild(del);
+      item.addEventListener('dragstart', (e) => {
+        e.dataTransfer.setData('text/plain', 'lib:' + person.id); e.dataTransfer.effectAllowed = 'copy';
+        dragBody = body; dragScrolling = true; startDragAutoScroll();
+      });
+      item.addEventListener('dragend', stopDragAutoScroll);
+      item.addEventListener('click', () => { selectedLibId = selectedLibId === person.id ? '' : person.id; renderEditor(); });
+      lib.appendChild(item);
+    }
+    body.appendChild(lib);
+    wrap.appendChild(body);
+
+    root.innerHTML = '';
+    root.appendChild(wrap);
+  }
+
+  function assign(slotIndex, personId) {
+    selectedLibId = '';
+    api(`/assign?slot=${slotIndex}&personId=${encodeURIComponent(personId)}`, { method: 'POST' });
+  }
+  function renameSlot(slotIndex, currentName) {
+    const name = prompt('Name for this spot (leave blank to remove a name-only spot):', currentName || '');
+    if (name === null) return;
+    api(`/slot/${slotIndex}/name?name=${encodeURIComponent(name.trim())}`, { method: 'POST' });
+  }
+  function renameLibrary(id, currentName) {
+    const name = prompt('Rename this photo:', currentName || '');
+    if (name === null) return;
+    api(`/library/${id}?name=${encodeURIComponent(name.trim())}`, { method: 'POST' });
+  }
+
+  /* ---------- lifecycle ---------- */
+  return {
+    start() {
+      moduleApi.setStatus('connecting', 'Connecting…');
+      const SYNC_ICON = '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M23 4v6h-6"/><path d="M1 20v-6h6"/><path d="M3.5 9a9 9 0 0 1 14.9-3.4L23 10M1 14l4.6 4.4A9 9 0 0 0 20.5 15"/></svg>';
+      const EDIT_ICON = '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 20h9"/><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4 12.5-12.5z"/></svg>';
+      moduleApi.header.addButton({
+        icon: SYNC_ICON,
+        title: 'Sync',
+        onClick() { moduleApi.setStatus('connecting', 'Syncing with Planning Center…'); api('/sync', { method: 'POST' }); },
+      });
+      const editBtn = moduleApi.header.addButton({ icon: EDIT_ICON, title: 'Edit board', onClick() { editing = !editing; editBtn.classList.toggle('active', editing); render(); } });
+      // Columns −/+ (touch-friendly; replaces the gear number field).
+      const MINUS_ICON = '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round"><path d="M5 12h14"/></svg>';
+      const PLUS_ICON = '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round"><path d="M12 5v14M5 12h14"/></svg>';
+      const bumpCols = (d) => {
+        const max = Math.max(1, state && state.slots ? state.slots.length : 12);
+        const next = Math.max(1, Math.min(max, resolveCols() + d));
+        moduleApi.saveInstanceSettings({ columns: next });
+        render();
+      };
+      moduleApi.header.addButton({ icon: MINUS_ICON, title: 'Fewer columns', onClick() { bumpCols(-1); } });
+      moduleApi.header.addButton({ icon: PLUS_ICON, title: 'More columns', onClick() { bumpCols(1); } });
+      const CHOIR_ICON = '<svg viewBox="0 0 24 24" width="13" height="13" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="6" cy="18" r="2.5"/><circle cx="17" cy="16" r="2.5"/><path d="M8.5 18V5l11-2v13"/><path d="M8.5 8.5l11-2"/></svg>';
+      choirBtn = moduleApi.header.addButton({ icon: CHOIR_ICON, title: 'Choir', onClick() { api('/choir', { method: 'POST' }); } });
+      moduleApi.fetch('/state').then((r) => r.json()).then((d) => { state = d.state; render(); }).catch(() => {});
+      stream = moduleApi.sse('/stream', {
+        error() { reportStatus(); },
+        events: {
+          state(e) {
+            try { state = JSON.parse(e.data); } catch { return; }
+            // While editing, don't yank a rename prompt out from under the user:
+            // re-render the editor only (state carries board + library).
+            render();
+          },
+        },
+      });
+    },
+    onResize() {},
+    stop() {
+      if (stream) { stream.close(); stream = null; }
+      stopConfetti();
+      stopParallax();
+      stopDragAutoScroll();
+      root.innerHTML = '';
+    },
+  };
+}

modules/band-lineup/matching.js

@@ -0,0 +1,198 @@
+'use strict';
+
+/**
+ * Slot ↔ Planning Center position matching for the Band Lineup module.
+ *
+ * A "slot" is a mic/pack label the operator wrote for a spot on stage, e.g.
+ * "[LEADER, VOX 1, ACOUSTIC] MIX 1". A scheduled person carries their PCO
+ * team-position name, e.g. "Vox 1" or "Acoustic / Worship Leader". We assign
+ * people to slots by loose token overlap — the same logic the backstage
+ * Electron app used, lifted here unchanged so the board matches what the booth
+ * is used to. Pure functions only: no I/O, so this file is unit-testable.
+ */
+
+function normalizeTeamName(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+/** Does a person's PCO team count as a band/stage team we display? `keywords` comes from admin config. */
+function isAllowedTeamName(value, keywords) {
+  const normalized = normalizeTeamName(value);
+  if (!normalized) return false;
+  return (keywords || []).some((kw) => {
+    const k = normalizeTeamName(kw);
+    return k && (normalized === k || normalized.includes(k));
+  });
+}
+
+function normalizeLabel(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Fold a single token to a canonical instrument/role word (drops mic/pack noise, pluralises down). */
+function normalizeToken(token) {
+  const normalized = String(token || '').trim().toLowerCase();
+  if (!normalized) return '';
+  if (/^\d+$/.test(normalized)) return '';
+  if (['mix', 'mic', 'slot', 'channel', 'ch', 'pack', 'wireless', 'input', 'headset'].includes(normalized)) return '';
+  if (['vox', 'vocal', 'vocalist', 'vocalists', 'vocals', 'singer', 'singers'].includes(normalized)) return 'vocals';
+  if (['keys', 'keyboard', 'keyboards'].includes(normalized)) return 'keys';
+  if (['drum', 'drums', 'drummer', 'drummers'].includes(normalized)) return 'drums';
+  if (['perc', 'percussionist', 'percussionists'].includes(normalized)) return 'percussion';
+  if (['gtr', 'guitar', 'guitars'].includes(normalized)) return 'guitar';
+  if (['electric', 'electricguitar'].includes(normalized)) return 'electric';
+  if (['acoustic', 'acousticguitar'].includes(normalized)) return 'acoustic';
+  if (['b', 'bandleader', 'leader', 'lead'].includes(normalized)) return normalized === 'b' ? '' : 'leader';
+  if (['worship', 'calltoworship'].includes(normalized)) return normalized === 'calltoworship' ? 'call' : normalized;
+  if (normalized.endsWith('s') && normalized.length > 4) return normalized.slice(0, -1);
+  return normalized;
+}
+
+function labelTokens(value) {
+  const normalized = normalizeLabel(value);
+  if (!normalized) return [];
+  const tokens = normalized.split(' ').map((t) => normalizeToken(t)).filter(Boolean);
+  if (!tokens.length && normalized) return [normalized];
+  return [...new Set(tokens)];
+}
+
+/**
+ * The role part of a slot label to match on: the bracketed content when present
+ * ("[VOX 2] MIX 2" → "VOX 2, "), else the whole label ("STAGE MANAGER"). This
+ * drops the "MIX n / MC n / HEADSET" mic-assignment noise so a mic number can't
+ * be mistaken for a position number.
+ */
+function slotRoleText(label) {
+  const brackets = String(label || '').match(/\[([^\]]*)\]/g);
+  if (brackets && brackets.length) return brackets.map((b) => b.slice(1, -1)).join(', ');
+  return String(label || '');
+}
+
+/** The set of standalone numbers in a label ("vox 2" → {"2"}). */
+function numbersIn(value) {
+  return new Set(normalizeLabel(value).split(' ').filter((t) => /^\d+$/.test(t)));
+}
+
+/** 0–~140 similarity between a slot label and a PCO position name; higher is a better fit. */
+function scoreMatch(slotLabel, positionLabel) {
+  const slotNormalized = normalizeLabel(slotLabel);
+  const positionNormalized = normalizeLabel(positionLabel);
+  if (!slotNormalized || !positionNormalized) return 0;
+  // A numbered role only matches the same number: "Vox 3" must not take "Vox 2".
+  const slotNums = numbersIn(slotLabel);
+  const posNums = numbersIn(positionLabel);
+  if (slotNums.size && posNums.size && ![...posNums].some((n) => slotNums.has(n))) return 0;
+  if (slotNormalized === positionNormalized) return 120;
+  if (slotNormalized.includes(positionNormalized) || positionNormalized.includes(slotNormalized)) return 95;
+
+  const slotTokens = labelTokens(slotLabel);
+  const positionTokens = labelTokens(positionLabel);
+  if (!slotTokens.length || !positionTokens.length) return 0;
+
+  const positionSet = new Set(positionTokens);
+  const slotSet = new Set(slotTokens);
+  const overlap = slotTokens.filter((t) => positionSet.has(t));
+  if (!overlap.length) return 0;
+
+  const overlapCount = overlap.length;
+  const slotCoverage = overlapCount / slotSet.size;
+  const positionCoverage = overlapCount / positionSet.size;
+  const sharedPhrase = overlap.join(' ');
+
+  let score = Math.round(slotCoverage * 70 + positionCoverage * 20 + overlapCount * 4);
+  if (slotCoverage === 1) score += 18;
+  if (positionCoverage === 1) score += 10;
+  if (sharedPhrase && slotNormalized.includes(sharedPhrase) && positionNormalized.includes(sharedPhrase)) score += 8;
+  return score;
+}
+
+/**
+ * Assign scheduled members to the ordered slot list. Greedy by best score, each
+ * member used once. Returns an array aligned to `slots`, each entry the chosen
+ * member or null. `MIN_SCORE` keeps a weak coincidence from claiming a slot.
+ */
+const MIN_SCORE = 60;
+function assignMembersToSlots(slots, members) {
+  const pool = members.slice();
+  return slots.map((slotLabel) => {
+    const role = slotRoleText(slotLabel);
+    let bestIndex = -1;
+    let bestScore = MIN_SCORE - 1;
+    for (let i = 0; i < pool.length; i += 1) {
+      const score = scoreMatch(role, pool[i].label);
+      if (score > bestScore) { bestScore = score; bestIndex = i; }
+    }
+    if (bestIndex < 0) return null;
+    return pool.splice(bestIndex, 1)[0];
+  });
+}
+
+/**
+ * Best library photo for a Planning Center person, matched by name so Sync can use the folder
+ * photo instead of the PCO headshot. Handles full names, "First L" and first-name-only files,
+ * preferring the most specific. Returns the entry, or null when there's no confident, UNAMBIGUOUS
+ * match (e.g. two people share a first name and the photo is first-name-only) — then PCO's photo is used.
+ * `entries` is [{ ...whatever, name }].
+ */
+function bestLibraryMatch(pcoName, entries) {
+  const target = normalizeLabel(pcoName);
+  if (!target) return null;
+  const T = target.split(' ').filter(Boolean);
+  const scoreOf = (name) => {
+    const ln = normalizeLabel(name);
+    if (!ln) return 0;
+    if (ln === target) return 100; // exact full name
+    const L = ln.split(' ').filter(Boolean);
+    if (!L.length || !T.length) return 0;
+    // Align the library name against a leading run of the person's name, token by token.
+    // Every library token must equal the person's token in that position — except the LAST
+    // library token, which may be an initial/prefix ("m" of "Moniz"). This makes "Brian M"
+    // match "Brian Moniz" and "Alex" match "Alex Gaitan", but NOT "Alex" → "Alexander Zinni".
+    let ok = true; let exact = 0; let usedPrefix = false;
+    for (let k = 0; k < L.length; k += 1) {
+      const lt = L[k]; const tt = T[k];
+      if (!tt) { ok = false; break; }
+      if (lt === tt) { exact += 1; continue; }
+      if (k === L.length - 1 && tt.startsWith(lt)) { usedPrefix = true; continue; }
+      ok = false; break;
+    }
+    if (ok) {
+      if (L.length >= 2) return usedPrefix ? 86 : 92;   // "brian m" / "alex gaitan"
+      if (exact === 1) return 90;                        // first name matches exactly ("alex")
+      if (usedPrefix) return 45;                         // "alex" vs "alexander" — too ambiguous
+    }
+    // Otherwise: a library surname that appears anywhere in the person's name.
+    const last = L[L.length - 1];
+    if (last && last.length >= 3 && T.includes(last)) return 78;
+    return 0;
+  };
+  let best = null;
+  let bestScore = 0;
+  let tie = false;
+  for (const e of entries) {
+    const s = scoreOf(e.name);
+    if (s > bestScore) { bestScore = s; best = e; tie = false; }
+    else if (s === bestScore && s > 0) tie = true;
+  }
+  if (bestScore < 60 || tie) return null; // no confident / unambiguous winner → PCO photo
+  return best;
+}
+
+module.exports = {
+  normalizeTeamName,
+  isAllowedTeamName,
+  bestLibraryMatch,
+  normalizeLabel,
+  normalizeToken,
+  labelTokens,
+  slotRoleText,
+  numbersIn,
+  scoreMatch,
+  assignMembersToSlots,
+  MIN_SCORE,
+};

modules/band-lineup/matching.test.js

@@ -0,0 +1,67 @@
+'use strict';
+const assert = require('assert');
+const { assignMembersToSlots, isAllowedTeamName, slotRoleText, scoreMatch } = require('./matching');
+
+const SLOTS = [
+  '[LEADER, VOX 1, ACOUSTIC] MIX 1', '[VOX 2] MIX 2', '[VOX 3] MIX 3', '[VOX 4] MIX 4',
+  '[GUITAR, LEAD] MIX 5', '[BASS] MIX 6', '[VOX 5] MIX 7', '[PIANO]', '[DRUMS]',
+  '[KEYS 2]', '[CALL TO WORSHIP] MC2', 'STAGE MANAGER', '[MC] MC1', '[SPEAKER] HEADSET',
+];
+const M = (label) => ({ label, name: label });
+const members = [
+  M('Vox 3'), M('Vox 2'), M('Vox 1'), M('Guitar / Lead'), M('Bass'), M('Piano'), M('Drums'), M('MC'), M('Keys 2'),
+];
+const out = assignMembersToSlots(SLOTS, members).map((m) => (m ? m.label : null));
+
+// Numbered vocals land in the RIGHT slot (this is the swap bug we fixed).
+assert.strictEqual(out[0], 'Vox 1', 'slot 0 → Vox 1');
+assert.strictEqual(out[1], 'Vox 2', 'slot 1 → Vox 2');
+assert.strictEqual(out[2], 'Vox 3', 'slot 2 → Vox 3');
+assert.strictEqual(out[3], null, 'slot 3 (Vox 4) unfilled — nobody scheduled');
+assert.strictEqual(out[4], 'Guitar / Lead', 'slot 4 → Guitar/Lead');
+assert.strictEqual(out[5], 'Bass', 'slot 5 → Bass');
+assert.strictEqual(out[6], null, 'slot 6 (Vox 5) unfilled');
+assert.strictEqual(out[7], 'Piano', 'slot 7 → Piano');
+assert.strictEqual(out[8], 'Drums', 'slot 8 → Drums');
+assert.strictEqual(out[9], 'Keys 2', 'slot 9 → Keys 2');
+assert.strictEqual(out[12], 'MC', 'slot 12 → MC');
+
+// A different number never matches.
+assert.strictEqual(scoreMatch(slotRoleText('[VOX 2] MIX 2'), 'Vox 3'), 0, 'Vox 3 must not match Vox 2 slot');
+// Mic number no longer pollutes: Vox 7 must not grab "[VOX 5] MIX 7".
+assert.strictEqual(scoreMatch(slotRoleText('[VOX 5] MIX 7'), 'Vox 7'), 0, 'Vox 7 must not match the MIX 7 slot');
+
+// Team allow-list (singular stems match plurals/variants via substring).
+assert.ok(isAllowedTeamName('Band', ['band', 'vocal']));
+assert.ok(isAllowedTeamName('Vocals', ['band', 'vocal']));
+assert.ok(isAllowedTeamName('Vocal Team', ['band', 'vocal']));
+assert.ok(!isAllowedTeamName('Video', ['band', 'vocal', 'production']));
+
+console.log('matching.test.js: all assertions passed ✓');
+console.log('assignment:', JSON.stringify(out));
+
+// --- bestLibraryMatch: folder-photo → PCO person by name ---
+{
+  const { bestLibraryMatch } = require('./matching');
+  const name = (n) => (e) => (e ? e.name : null);
+  const lib = [
+    { id: 'a', name: 'Alex' }, { id: 'g', name: 'AlexG' }, { id: 'bm', name: 'Brian M' },
+    { id: 'c', name: 'Courtney' }, { id: 'gn', name: 'Gaitan' }, { id: 'wes', name: 'Wes' },
+  ];
+  const pick = (n, list = lib) => { const e = bestLibraryMatch(n, list); return e ? e.name : null; };
+  assert.strictEqual(pick('Alex Gaitan'), 'Alex', 'first name matches "Alex"');
+  assert.strictEqual(pick('Brian Moniz'), 'Brian M', '"Brian M" matches "Brian Moniz"');
+  assert.strictEqual(pick('Courtney Maranda'), 'Courtney', 'first name matches');
+  assert.strictEqual(pick('Alexander Zinni'), null, '"Alex" must NOT grab "Alexander Zinni"');
+  assert.strictEqual(pick('Wes Carter'), 'Wes', 'first name matches "Wes"');
+  // surname-named photo
+  assert.strictEqual(pick('Someone Gaitan'), 'Gaitan', 'surname photo matches by last name');
+  // two people share a first name + only a first-name photo → ambiguous only if two matches tie;
+  // here a single "Alex" photo still maps to whoever's first name is exactly Alex.
+  assert.strictEqual(pick('Alex Johnson'), 'Alex', 'first-name photo maps to any exact-first-name person');
+  // exact full name beats a first-name photo
+  assert.strictEqual(pick('Alex Gaitan', [{ id: 'x', name: 'Alex Gaitan' }, { id: 'a', name: 'Alex' }]), 'Alex Gaitan', 'exact full name wins');
+  // tie → no match (two identical-scoring photos)
+  assert.strictEqual(bestLibraryMatch('Chris Smith', [{ id: '1', name: 'Chris' }, { id: '2', name: 'Chris' }]), null, 'ambiguous tie → null');
+  console.log('bestLibraryMatch: all assertions passed ✓');
+}

modules/band-lineup/module.json

@@ -0,0 +1,154 @@
+{
+  "id": "band-lineup",
+  "name": "Band Lineup",
+  "version": "1.11.0",
+  "proddash": ">=1.4.0",
+  "description": "Stage lineup photos with mic/pack labels — a drag-in photo library plus optional Planning Center auto-fill",
+  "client": "client.js",
+  "server": "server.js",
+  "style": "style.css",
+  "minSize": {
+    "w": 4,
+    "h": 3
+  },
+  "defaultSize": {
+    "w": 8,
+    "h": 5
+  },
+  "configGroups": {
+    "Planning Center credentials": {
+      "collapsed": "whenSet",
+      "help": "Create a Personal Access Token at api.planningcenteronline.com and paste its Client ID + Secret here, or paste an OAuth 2.0 access token instead. Reading photos and birthdays needs People access on the token. Saved secrets never reach browsers."
+    },
+    "Stage": {
+      "help": "One mic/pack label per line, in the order they sit on stage. Scheduled people are matched into these by their Planning Center position (e.g. a line '[VOX 2] MIX 2' takes whoever is scheduled on Vox 2). Blank lines are empty spots."
+    },
+    "Photo library": {
+      "help": "Paste a Google Drive folder share link (set the folder to 'Anyone with the link → Viewer'). Every image is imported (file name → person's name) and kept in sync — add or remove photos in Drive and the board follows. A local folder path also works. If Drive can't be read, the board falls back to Planning Center photos."
+    }
+  },
+  "configSchema": {
+    "appId": {
+      "type": "string",
+      "label": "Client ID",
+      "default": "",
+      "group": "Planning Center credentials"
+    },
+    "secret": {
+      "type": "password",
+      "label": "Secret",
+      "default": "",
+      "group": "Planning Center credentials"
+    },
+    "accessToken": {
+      "type": "password",
+      "label": "OAuth 2.0 access token (instead of Client ID + Secret)",
+      "default": "",
+      "group": "Planning Center credentials"
+    },
+    "serviceTypeId": {
+      "type": "select",
+      "label": "Service type",
+      "default": "",
+      "optionsRoute": "/service-types"
+    },
+    "planId": {
+      "type": "select",
+      "label": "Plan",
+      "default": "",
+      "options": [
+        {
+          "value": "",
+          "label": "Automatic — today's plan, else the next upcoming"
+        }
+      ],
+      "optionsRoute": "/plans",
+      "optionsDependsOn": "serviceTypeId"
+    },
+    "teams": {
+      "type": "text",
+      "label": "Teams to include",
+      "default": "Band\nWorship\nVocal\nProduction\nCommunication",
+      "help": "One team name (or keyword) per line. A person on any matching Planning Center team is eligible for the board."
+    },
+    "slots": {
+      "type": "text",
+      "label": "Stage slots",
+      "default": "[LEADER, VOX 1, ACOUSTIC] MIX 1\n[VOX 2] MIX 2\n[VOX 3] MIX 3\n[VOX 4] MIX 4\n[GUITAR, LEAD] MIX 5\n[BASS] MIX 6\n[VOX 5] MIX 7\n[PIANO]\n[DRUMS]\n[KEYS 2]\n[CALL TO WORSHIP] MC2\nSTAGE MANAGER\n[MC] MC1\n[SPEAKER] HEADSET",
+      "group": "Stage"
+    },
+    "columns": {
+      "type": "number",
+      "label": "Columns",
+      "default": 7,
+      "group": "Stage",
+      "help": "Default slots per row (each screen can still adjust with the − / + buttons in its title bar)."
+    },
+    "photoFolder": {
+      "type": "string",
+      "label": "Google Drive folder link",
+      "default": "",
+      "group": "Photo library",
+      "help": "e.g. https://drive.google.com/drive/folders/…  (a local folder path also works). Leave blank to use Planning Center photos only."
+    }
+  },
+  "instanceGroups": {
+    "Birthday": {
+      "toggle": "birthdays"
+    }
+  },
+  "instanceSchema": {
+    "showNames": {
+      "type": "boolean",
+      "label": "Names",
+      "default": true
+    },
+    "showLabels": {
+      "type": "boolean",
+      "label": "Mic labels",
+      "default": true
+    },
+    "parallax": {
+      "type": "boolean",
+      "label": "Parallax motion",
+      "default": true
+    },
+    "birthdays": {
+      "type": "switch",
+      "label": "Birthday confetti",
+      "default": true,
+      "group": "Birthday"
+    },
+    "birthdayIntensity": {
+      "type": "select",
+      "label": "Intensity",
+      "default": "subtle",
+      "group": "Birthday",
+      "showWhen": "birthdays",
+      "options": [
+        {
+          "value": "subtle",
+          "label": "Subtle"
+        },
+        {
+          "value": "full",
+          "label": "Full"
+        }
+      ]
+    },
+    "birthdayTest": {
+      "type": "select",
+      "label": "Force on (test)",
+      "default": "",
+      "group": "Birthday",
+      "showWhen": "birthdays",
+      "options": [
+        {
+          "value": "",
+          "label": "Off"
+        }
+      ],
+      "optionsRoute": "/people"
+    }
+  }
+}

modules/band-lineup/server.js

@@ -0,0 +1,764 @@
+'use strict';
+
+/**
+ * Band Lineup — server part.
+ *
+ * Owns the shared stage board and the uploaded-photo library, plus the one
+ * Planning Center connection. The board is server-side and global: whoever
+ * edits it (drag a library photo onto a slot, rename, clear) changes it for
+ * every Band Lineup tile on every screen, over SSE. Planning Center sync is an
+ * optional auto-fill — it only fills slots nobody has placed by hand. Browsers
+ * never talk to Planning Center directly.
+ *
+ *   GET  /state              → { state }            (board + library; instant paint)
+ *   GET  /stream             → SSE `state` events   (change-detected, heartbeat)
+ *   GET  /library            → { people }            (the drag-in photo library)
+ *   GET  /service-types      → { options }          (admin "Service type" select)
+ *   GET  /plans              → { options }          (admin "Plan" select)
+ *   GET  /people             → { options }          (gear "Force birthday" select)
+ *   GET  /photo/<file>       → image bytes (library + cached PCO photos)
+ *   POST /library/<id>       → rename / set birthday / replace photo (raw image body; ?name=&birthday=)
+ *   POST /library/<id>/delete→ remove from the library and any slot
+ *   POST /assign             → ?slot=&personId=  place a library person in a slot
+ *   POST /move               → ?from=&to=  move or swap one slot's occupant
+ *   POST /slot/<index>/name  → ?name=  rename the occupant (or make a name-only spot)
+ *   POST /slot/<index>/clear → empty the slot
+ *   POST /choir              → ?on=1|0  toggle the extra CHOIR slot (shared)
+ *   POST /sync               → run a Planning Center + photo-folder sync now
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const { isAllowedTeamName, assignMembersToSlots, bestLibraryMatch } = require('./matching');
+
+const DEFAULT_API_BASE = 'https://api.planningcenteronline.com';
+const API_BASE = String(process.env.BAND_LINEUP_API_BASE || process.env.PCO_PLAN_API_BASE || DEFAULT_API_BASE).replace(/\/+$/, '');
+const SERVICES = '/services/v2';
+const PEOPLE = '/people/v2';
+
+const REQUEST_TIMEOUT_MS = 12000;
+const PHOTO_TIMEOUT_MS = 15000;
+const MIN_POLL_S = 10;
+const RETRY_MS = 15000;
+const HEARTBEAT_MS = 15000;
+const MODULE_ID = 'band-lineup';
+const MAX_UPLOAD = 20 * 1024 * 1024;
+
+let current = null; // set by init(), read by routes; rebuilt together on remount
+
+/* ── data directory (library + board + photo cache live here, never in the repo) ── */
+
+function resolveDataDir() {
+  const home = os.homedir();
+  const fromEnv = String(process.env.PRODDASH_DATA_DIR || '').trim();
+  const root = path.join(__dirname, '..', '..');
+  if (fromEnv) return path.resolve(root, fromEnv);
+  if (process.platform === 'win32') return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'ProdDash');
+  if (process.platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'ProdDash');
+  return path.join(process.env.XDG_CONFIG_HOME || path.join(home, '.config'), 'proddash');
+}
+
+/* ── small helpers ─────────────────────────────────────────────────── */
+
+function lines(text) { return String(text || '').split('\n').map((s) => s.trim()); }
+function nonEmptyLines(text) { return lines(text).filter(Boolean); }
+function localYmd(d) { return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`; }
+function birthdayMmdd(raw) {
+  const s = String(raw || '').trim();
+  const full = s.match(/^\d{4}-(\d{2})-(\d{2})$/);
+  if (full) return `${full[1]}-${full[2]}`;
+  return /^\d{2}-\d{2}$/.test(s) ? s : '';
+}
+function birthdayWeekSet(now = new Date()) {
+  const daysSinceWed = (now.getDay() - 3 + 7) % 7;
+  const start = new Date(now.getFullYear(), now.getMonth(), now.getDate() - daysSinceWed);
+  const set = new Set();
+  for (let i = 0; i < 7; i += 1) {
+    const d = new Date(start.getFullYear(), start.getMonth(), start.getDate() + i);
+    set.add(`${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`);
+  }
+  return set;
+}
+function extFromContentType(ct) {
+  const t = String(ct || '').toLowerCase();
+  if (t.includes('png')) return 'png';
+  if (t.includes('webp')) return 'webp';
+  if (t.includes('gif')) return 'gif';
+  return 'jpg';
+}
+function contentTypeForFile(file) {
+  const e = path.extname(file).toLowerCase();
+  if (e === '.png') return 'image/png';
+  if (e === '.webp') return 'image/webp';
+  if (e === '.gif') return 'image/gif';
+  return 'image/jpeg';
+}
+function json(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+  res.end(JSON.stringify(body));
+}
+function readJsonFile(file, fallback) { try { return JSON.parse(fs.readFileSync(file, 'utf8')) || fallback; } catch { return fallback; } }
+function newId() { return crypto.randomBytes(6).toString('hex'); }
+function photoUrlFor(file) { return file ? `/api/modules/${MODULE_ID}/photo/${encodeURIComponent(file)}` : ''; }
+
+/* ── Planning Center client ────────────────────────────────────────── */
+
+function createPcoClient(config) {
+  const token = String(config.accessToken || '').trim();
+  const appId = String(config.appId || '').trim();
+  const secret = String(config.secret || '');
+  let auth = '';
+  if (token) auth = `Bearer ${token}`;
+  else if (appId && secret) auth = 'Basic ' + Buffer.from(`${appId}:${secret}`).toString('base64');
+  const configured = Boolean(auth);
+
+  async function get(target, params) {
+    const url = new URL(/^https?:\/\//.test(target) ? target : API_BASE + target);
+    for (const [k, v] of Object.entries(params || {})) url.searchParams.set(k, String(v));
+    let response;
+    try {
+      response = await fetch(url, { headers: { Authorization: auth, Accept: 'application/json' }, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    } catch (err) {
+      const e = new Error(`Planning Center unreachable: ${err?.message || err}`); e.network = true; throw e;
+    }
+    if (!response.ok) { const e = new Error(`Planning Center ${response.status}`); e.status = response.status; throw e; }
+    const text = await response.text();
+    return text ? JSON.parse(text) : {};
+  }
+  async function getAll(target, params) {
+    const data = []; const included = []; let next = null;
+    let query = { per_page: 100, ...(params || {}) }; let guard = 0;
+    do {
+      const body = next ? await get(next) : await get(target, query);
+      if (Array.isArray(body.data)) data.push(...body.data);
+      if (Array.isArray(body.included)) included.push(...body.included);
+      next = body?.links?.next || null; query = null; guard += 1;
+    } while (next && guard < 50);
+    return { data, included };
+  }
+  return { configured, get, getAll };
+}
+
+/* ── Google Drive (public "anyone with the link" folder, no API key) ── */
+
+const DRIVE_TIMEOUT_MS = 30000;
+const DRIVE_UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15) AppleWebKit/537.36';
+
+/** Pull the folder id out of a Drive share link (or '' if it isn't a Drive folder link). */
+function parseDriveFolderId(s) {
+  const str = String(s || '');
+  if (!/drive\.google\.com/i.test(str)) return '';
+  const m = /\/folders\/([A-Za-z0-9_-]{10,})/.exec(str) || /[?&]id=([A-Za-z0-9_-]{10,})/.exec(str);
+  return m ? m[1] : '';
+}
+
+/** List a public folder's files via Drive's embedded folder view — [{ id, name }]. */
+async function driveList(folderId) {
+  const resp = await fetch(`https://drive.google.com/embeddedfolderview?id=${encodeURIComponent(folderId)}#list`, {
+    headers: { 'User-Agent': DRIVE_UA }, redirect: 'follow', signal: AbortSignal.timeout(DRIVE_TIMEOUT_MS),
+  });
+  if (!resp.ok) throw new Error(`Drive folder list ${resp.status}`);
+  const html = await resp.text();
+  const out = []; const seen = new Set();
+  const re = /id="entry-([A-Za-z0-9_-]{20,})"[\s\S]*?flip-entry-title[^>]*>([^<]+)</g;
+  let m;
+  while ((m = re.exec(html))) {
+    const id = m[1]; const name = m[2].trim();
+    if (id && !seen.has(id)) { seen.add(id); out.push({ id, name }); }
+  }
+  return out;
+}
+
+/** Download one public Drive file at full resolution (falls back to a large thumbnail). */
+async function driveFetchImage(fileId) {
+  const base = 'https://drive.usercontent.google.com/download';
+  const opts = { headers: { 'User-Agent': DRIVE_UA }, redirect: 'follow', signal: AbortSignal.timeout(DRIVE_TIMEOUT_MS) };
+  let resp = await fetch(`${base}?id=${fileId}&export=download`, opts);
+  let ct = String(resp.headers.get('content-type') || '');
+  if (resp.ok && ct.startsWith('image/')) return { buf: Buffer.from(await resp.arrayBuffer()), ext: extFromContentType(ct) };
+  // Large-file virus-scan interstitial: grab the confirm token and retry.
+  if (ct.includes('text/html')) {
+    const html = await resp.text();
+    const conf = /name="confirm"\s+value="([^"]+)"/.exec(html) || /[?&]confirm=([0-9A-Za-z_-]+)/.exec(html);
+    const uuid = /name="uuid"\s+value="([^"]+)"/.exec(html);
+    if (conf) {
+      resp = await fetch(`${base}?id=${fileId}&export=download&confirm=${conf[1]}${uuid ? `&uuid=${uuid[1]}` : ''}`, opts);
+      ct = String(resp.headers.get('content-type') || '');
+      if (resp.ok && ct.startsWith('image/')) return { buf: Buffer.from(await resp.arrayBuffer()), ext: extFromContentType(ct) };
+    }
+  }
+  const th = await fetch(`https://drive.google.com/thumbnail?id=${fileId}&sz=w2000`, opts);
+  const tct = String(th.headers.get('content-type') || '');
+  if (th.ok && tct.startsWith('image/')) return { buf: Buffer.from(await th.arrayBuffer()), ext: extFromContentType(tct) };
+  throw new Error('not an image');
+}
+
+/* ── the module ────────────────────────────────────────────────────── */
+
+module.exports = {
+  init({ config, log }) {
+    const streams = new Set();
+    const dataDir = path.join(resolveDataDir(), MODULE_ID);
+    const photoDir = path.join(dataDir, 'photos');
+    const libraryPath = path.join(dataDir, 'library.json');
+    const boardPath = path.join(dataDir, 'board.json');
+    try { fs.mkdirSync(photoDir, { recursive: true }); } catch (err) { log(`cannot create ${photoDir}: ${err?.message || err}`); }
+
+    const slots = nonEmptyLines(config.slots).length ? lines(config.slots) : [];
+    const teamKeywords = nonEmptyLines(config.teams).length ? nonEmptyLines(config.teams) : ['band', 'worship', 'vocal', 'production', 'communication'];
+    const columns = Math.max(1, Number(config.columns) || 7);
+    const serviceTypeId = String(config.serviceTypeId || '').trim();
+    const planIdCfg = String(config.planId || '').trim();
+    // Photos folder: the admin "Photos folder" field wins when set; otherwise it's whatever the
+    // tile's "Choose folder…" picker saved into module state. Admin can't host a native picker
+    // (the shell renders plain fields), so the picker lives in the tile as the no-typing option.
+    const settingsPath = path.join(dataDir, 'settings.json');
+    const settings = readJsonFile(settingsPath, {}) || {};
+    const photoFolder = String(config.photoFolder || settings.photoFolder || '').trim(); // admin field (Drive link or local path)
+    let choirOn = Boolean(settings.choir); // optional extra "CHOIR" slot, toggled from the tile
+    function saveSettings() { try { fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2)); } catch (err) { log(`save settings failed: ${err?.message || err}`); } }
+
+    const CHOIR_LABEL = 'CHOIR';
+    // The board's slots plus an extra CHOIR spot when the toggle is on. Its index is slots.length,
+    // so its assignment persists in board.json across toggles.
+    const effectiveSlots = () => (choirOn ? slots.concat([CHOIR_LABEL]) : slots);
+
+    const pco = createPcoClient(config);
+
+    // Persisted, shared editor state.
+    let library = readJsonFile(libraryPath, {}); // { id: { name, file, birthday } }
+    let board = readJsonFile(boardPath, {});      // { slotIndex: { personId, name } }
+    function saveLibrary() { try { fs.writeFileSync(libraryPath, JSON.stringify(library, null, 2)); } catch (err) { log(`save library failed: ${err?.message || err}`); } }
+    function saveBoard() { try { fs.writeFileSync(boardPath, JSON.stringify(board, null, 2)); } catch (err) { log(`save board failed: ${err?.message || err}`); } }
+
+    let latest = clearedState();
+    let lastFrame = '';
+    let celebrateTimer = null;
+    let drivePollTimer = null;
+    let watcher = null;
+    let watchDebounce = null;
+    let stopped = false;
+    let syncing = false;
+
+    function clearedState() {
+      return {
+        configured: pco.configured, serviceTypeSet: Boolean(serviceTypeId),
+        reachable: false, lastError: '', lastFetched: 0, columns,
+        plan: null,
+        slots: effectiveSlots().map((label, index) => ({ index, label, person: null })),
+        library: [], choir: choirOn,
+      };
+    }
+
+    function libraryList() {
+      return Object.entries(library)
+        .map(([id, v]) => ({ id, name: v.name || '', photo: photoUrlFor(v.file || ''), birthday: v.birthday || '' }))
+        .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+    }
+
+    function broadcast() {
+      if (!streams.size) return;
+      let frame; try { frame = JSON.stringify(latest); } catch { return; }
+      if (frame === lastFrame) return;
+      lastFrame = frame;
+      const payload = `event: state\ndata: ${frame}\n\n`;
+      for (const res of streams) { try { res.write(payload); } catch { streams.delete(res); } }
+    }
+
+    async function listPlans(stId) {
+      const [future, past] = await Promise.all([
+        pco.get(`${SERVICES}/service_types/${encodeURIComponent(stId)}/plans`, { filter: 'future', order: 'sort_date', per_page: 6 }),
+        pco.get(`${SERVICES}/service_types/${encodeURIComponent(stId)}/plans`, { filter: 'past', order: '-sort_date', per_page: 2 }),
+      ]);
+      const rows = [...(future.data || []), ...(past.data || [])];
+      return rows.map((rec) => ({
+        id: String(rec.id), sortDate: Date.parse(rec.attributes?.sort_date || '') || 0,
+        title: String(rec.attributes?.title || rec.attributes?.series_title || '').trim(),
+        dates: String(rec.attributes?.dates || rec.attributes?.short_dates || '').trim(),
+      }));
+    }
+    function pickPlan(plans) {
+      if (planIdCfg) return plans.find((p) => p.id === planIdCfg) || { id: planIdCfg, title: '', dates: '' };
+      const todayY = localYmd(new Date());
+      const today = plans.find((p) => p.sortDate && localYmd(new Date(p.sortDate)) === todayY);
+      if (today) return today;
+      const now = Date.now();
+      const upcoming = plans.filter((p) => p.sortDate >= now - 12 * 3600000).sort((a, b) => a.sortDate - b.sortDate);
+      return upcoming[0] || plans.sort((a, b) => b.sortDate - a.sortDate)[0] || null;
+    }
+
+    async function cachePcoPhoto(personId, url) {
+      if (!url) return '';
+      const hash = crypto.createHash('sha1').update(url).digest('hex').slice(0, 8);
+      const existing = fs.existsSync(photoDir) ? fs.readdirSync(photoDir).find((f) => f.startsWith(`pco-${personId}-${hash}.`)) : null;
+      if (existing) return existing;
+      try {
+        const resp = await fetch(url, { signal: AbortSignal.timeout(PHOTO_TIMEOUT_MS) });
+        if (!resp.ok) return '';
+        const buf = Buffer.from(await resp.arrayBuffer());
+        if (!buf.length) return '';
+        const file = `pco-${personId}-${hash}.${extFromContentType(resp.headers.get('content-type'))}`;
+        fs.writeFileSync(path.join(photoDir, file), buf);
+        return file;
+      } catch { return ''; }
+    }
+
+    /**
+     * Import a folder of photos into the library and keep it in sync: new files are added
+     * (filename → name), changed files refreshed, and files removed from the folder dropped
+     * from the library (and any slot they filled). Manually-uploaded photos (no folderKey) are
+     * left alone, so a folder and hand-uploads can coexist. Returns true if anything changed.
+     */
+    const IMG_RE = /\.(jpe?g|png|webp|gif)$/i;
+    const cleanNameFromFile = (f) => f.replace(/\.[^.]+$/, '').replace(/[_-]+/g, ' ').trim();
+    function extOf(f) { const m = f.match(IMG_RE); const e = (m ? m[1] : 'jpg').toLowerCase(); return e === 'jpeg' ? 'jpg' : e; }
+    function scanFolder() {
+      if (!photoFolder) return false;
+      let names; try { names = fs.readdirSync(photoFolder); } catch { return false; } // folder gone/unreadable
+      const files = names.filter((n) => IMG_RE.test(n));
+      const present = new Set(files);
+      const byKey = new Map();
+      for (const [id, v] of Object.entries(library)) if (v.folderKey) byKey.set(v.folderKey, id);
+      let changed = false;
+      for (const f of files) {
+        let mtime = 0; try { mtime = fs.statSync(path.join(photoFolder, f)).mtimeMs; } catch { continue; }
+        const id = byKey.get(f);
+        try {
+          if (id) {
+            const v = library[id];
+            if (v.mtime === mtime && v.file) continue; // unchanged
+            const dest = `lib-${id}.${extOf(f)}`;
+            fs.copyFileSync(path.join(photoFolder, f), path.join(photoDir, dest));
+            if (v.file && v.file !== dest) { try { fs.unlinkSync(path.join(photoDir, v.file)); } catch { /* ignore */ } }
+            v.file = dest; v.mtime = mtime; changed = true; // keep any in-app rename/birthday
+          } else {
+            const nid = newId();
+            const dest = `lib-${nid}.${extOf(f)}`;
+            fs.copyFileSync(path.join(photoFolder, f), path.join(photoDir, dest));
+            library[nid] = { name: cleanNameFromFile(f), file: dest, birthday: '', folderKey: f, mtime };
+            changed = true;
+          }
+        } catch (err) { log(`folder import of ${f} failed: ${err?.message || err}`); }
+      }
+      for (const [id, v] of Object.entries(library)) {
+        if (v.folderKey && !present.has(v.folderKey)) {
+          if (v.file) { try { fs.unlinkSync(path.join(photoDir, v.file)); } catch { /* ignore */ } }
+          delete library[id];
+          for (const [slot, b] of Object.entries(board)) if (b && b.personId === id) delete board[slot];
+          changed = true;
+        }
+      }
+      // De-duplicate: a hand-uploaded photo that shares a name with a folder photo is dropped
+      // (the folder wins), and any slot it filled repoints to the folder photo. Fixes the case
+      // where someone uploaded people by hand and then pointed at a folder of the same people.
+      const folderByName = new Map();
+      for (const [id, v] of Object.entries(library)) if (v.folderKey && v.name) folderByName.set(normName(v.name), id);
+      for (const [id, v] of Object.entries(library)) {
+        if (v.folderKey || !v.name) continue;
+        const keepId = folderByName.get(normName(v.name));
+        if (!keepId) continue;
+        if (v.file) { try { fs.unlinkSync(path.join(photoDir, v.file)); } catch { /* ignore */ } }
+        for (const [slot, b] of Object.entries(board)) if (b && b.personId === id) b.personId = keepId;
+        delete library[id];
+        changed = true;
+      }
+      if (changed) { saveLibrary(); saveBoard(); }
+      return changed;
+    }
+
+    // Import a public Google Drive folder into the library (file name → name), keeping it in sync.
+    // Keyed by Drive file id (folderKey "drive:<id>"). On a list failure we keep the last-good library.
+    async function scanDrive(folderId) {
+      let files;
+      try { files = await driveList(folderId); } catch (err) { log(`Drive list failed: ${err?.message || err}`); return false; }
+      files = files.filter((f) => IMG_RE.test(f.name));
+      const present = new Set(files.map((f) => `drive:${f.id}`));
+      const have = new Set();
+      for (const v of Object.values(library)) if (v.folderKey && v.folderKey.startsWith('drive:')) have.add(v.folderKey);
+      let changed = false;
+      for (const f of files) {
+        const key = `drive:${f.id}`;
+        if (have.has(key)) continue; // already imported (by Drive file id)
+        let img;
+        try { img = await driveFetchImage(f.id); } catch (err) { log(`Drive image ${f.name} failed: ${err?.message || err}`); continue; }
+        const nid = newId();
+        const dest = `lib-${nid}.${img.ext}`;
+        try { fs.writeFileSync(path.join(photoDir, dest), img.buf); library[nid] = { name: cleanNameFromFile(f.name), file: dest, birthday: '', folderKey: key }; changed = true; }
+        catch (err) { log(`write ${dest} failed: ${err?.message || err}`); }
+      }
+      for (const [id, v] of Object.entries(library)) {
+        if (v.folderKey && v.folderKey.startsWith('drive:') && !present.has(v.folderKey)) {
+          if (v.file) { try { fs.unlinkSync(path.join(photoDir, v.file)); } catch { /* ignore */ } }
+          delete library[id];
+          for (const [slot, b] of Object.entries(board)) if (b && b.personId === id) delete board[slot];
+          changed = true;
+        }
+      }
+      // Drive photo wins over a same-named hand-upload (repoint any slot to it).
+      const driveByName = new Map();
+      for (const [id, v] of Object.entries(library)) if (v.folderKey && v.folderKey.startsWith('drive:') && v.name) driveByName.set(normName(v.name), id);
+      for (const [id, v] of Object.entries(library)) {
+        if ((v.folderKey && v.folderKey.startsWith('drive:')) || !v.name) continue;
+        const keepId = driveByName.get(normName(v.name));
+        if (!keepId) continue;
+        if (v.file) { try { fs.unlinkSync(path.join(photoDir, v.file)); } catch { /* ignore */ } }
+        for (const [slot, b] of Object.entries(board)) if (b && b.personId === id) b.personId = keepId;
+        delete library[id]; changed = true;
+      }
+      if (changed) { saveLibrary(); saveBoard(); }
+      return changed;
+    }
+
+    // Import the configured photo source — a Drive folder link, or a local folder path.
+    async function syncPhotos() {
+      const fid = parseDriveFolderId(photoFolder);
+      if (fid) return scanDrive(fid);
+      if (photoFolder) return scanFolder();
+      return false;
+    }
+
+    function startWatch() {
+      if (parseDriveFolderId(photoFolder)) return; // Drive folders are polled, not fs.watched
+      if (!photoFolder) return;
+      try {
+        watcher = fs.watch(photoFolder, { persistent: false }, () => {
+          clearTimeout(watchDebounce);
+          watchDebounce = setTimeout(() => { if (!stopped && scanFolder()) rebuildLocal(); }, 800);
+        });
+        log(`watching photo folder ${photoFolder}`);
+      } catch (err) { log(`cannot watch photo folder: ${err?.message || err}`); }
+    }
+    function setChoir(on) { choirOn = Boolean(on); settings.choir = choirOn; saveSettings(); rebuildLocal(); }
+
+    // Remove cached PCO photos no longer referenced. Library files (lib-*) are never pruned here.
+    function prunePcoPhotos(keep) {
+      let files; try { files = fs.readdirSync(photoDir); } catch { return; }
+      for (const f of files) { if (f.startsWith('pco-') && !keep.has(f)) { try { fs.unlinkSync(path.join(photoDir, f)); } catch { /* ignore */ } } }
+    }
+
+    const normName = (s) => String(s || '').trim().toLowerCase().replace(/\s+/g, ' ');
+
+    // Resolve one board slot to a display person (or null). The board is the source of truth —
+    // there is no live PCO overlay, so clearing a slot stays cleared until the next Sync. A PCO
+    // entry prefers a same-named library photo, so uploading a photo updates the board without a re-sync.
+    function resolveSlot(i, weekSet, keep) {
+      const e = board[String(i)];
+      if (!e) return null;
+      let name = '', file = '', birthday = '', manual = true, personId = '';
+      if (e.pco) {
+        // The photo (folder photo, or PCO headshot) was chosen at Sync time — use it as-is.
+        manual = false; personId = e.pco.personId || '';
+        name = String(e.pco.name || '').trim();
+        file = e.pco.file || '';
+        birthday = e.pco.birthday || '';
+      } else if (e.personId) {
+        const lib = library[e.personId];
+        if (!lib) return null; // its library photo was deleted → slot is empty
+        personId = e.personId;
+        name = String(e.name || lib.name || '').trim();
+        file = lib.file || ''; birthday = lib.birthday || '';
+      } else if (e.name) {
+        name = String(e.name).trim();
+      } else return null;
+      if (file) keep.add(file);
+      return { name, photo: photoUrlFor(file), birthday, celebrating: Boolean(birthday) && weekSet.has(birthday), manual, personId };
+    }
+
+    // Repaint the display from the board (no Planning Center calls). Cheap — used after every edit
+    // and on a slow timer so a birthday week rolling over lights up on its own.
+    function renderBoard() {
+      const weekSet = birthdayWeekSet();
+      const keep = new Set();
+      const outSlots = effectiveSlots().map((label, i) => ({ index: i, label, person: resolveSlot(i, weekSet, keep) }));
+      for (const v of Object.values(library)) if (v.file) keep.add(v.file);
+      prunePcoPhotos(keep);
+      latest = {
+        configured: pco.configured, serviceTypeSet: Boolean(serviceTypeId),
+        reachable: latest.reachable, lastError: latest.lastError || '', lastFetched: latest.lastFetched || 0,
+        columns, plan: latest.plan || null, slots: outSlots, library: libraryList(), choir: choirOn,
+      };
+    }
+
+    function rebuildLocal() { renderBoard(); broadcast(); }
+
+    // Pull the current plan from Planning Center and write matched people INTO the board. Fills only
+    // slots nobody placed by hand; drops PCO entries no longer scheduled; leaves manual placements be.
+    async function syncNow() {
+      if (syncing) return;
+      syncing = true;
+      try {
+        await syncPhotos(); // import the photo source (Drive folder or local path) on every sync
+        if (pco.configured && serviceTypeId) {
+        const plan = pickPlan(await listPlans(serviceTypeId));
+        latest.plan = plan ? { title: plan.title, dates: plan.dates } : null;
+        if (!plan) { latest.reachable = true; latest.lastError = 'No plan found for that service type.'; }
+        else {
+
+        const tm = await pco.getAll(`${SERVICES}/service_types/${encodeURIComponent(serviceTypeId)}/plans/${encodeURIComponent(plan.id)}/team_members`, { include: 'person,team' });
+        const byKey = new Map((tm.included || []).map((e) => [`${e.type}:${e.id}`, e]));
+        const members = []; const seen = new Set();
+        for (const m of tm.data || []) {
+          const status = String(m.attributes?.status || '').trim();
+          if (status === 'D' || /^declined$/i.test(status)) continue;
+          const personId = String(m.relationships?.person?.data?.id || '');
+          const team = byKey.get(`Team:${String(m.relationships?.team?.data?.id || '')}`);
+          if (!isAllowedTeamName(String(team?.attributes?.name || ''), teamKeywords)) continue;
+          const person = byKey.get(`Person:${personId}`);
+          members.push({
+            personId,
+            name: String(person?.attributes?.full_name || person?.attributes?.name || m.attributes?.name || 'Unknown').trim() || 'Unknown',
+            label: String(m.attributes?.team_position_name || '').trim(),
+            photoUrl: String(person?.attributes?.photo_url || person?.attributes?.photo_thumbnail_url || '').trim(),
+          });
+          if (personId) seen.add(personId);
+        }
+        const bdays = new Map();
+        for (const id of seen) { try { const b = await pco.get(`${PEOPLE}/people/${encodeURIComponent(id)}`, { 'fields[Person]': 'birthdate' }); bdays.set(id, birthdayMmdd(b?.data?.attributes?.birthdate)); } catch { bdays.set(id, ''); } }
+        for (const m of members) m.birthday = bdays.get(m.personId) || '';
+
+        const libEntries = Object.entries(library).map(([id, v]) => ({ id, name: v.name, file: v.file }));
+
+        // Slots a person is sitting in by hand — don't fill them, and don't place that same person twice.
+        const eff = effectiveSlots();
+        const openIdx = []; const manualNames = new Set();
+        for (let i = 0; i < eff.length; i += 1) {
+          const e = board[String(i)];
+          if (e && (e.personId || e.name)) {
+            const nm = e.personId ? (library[e.personId] && library[e.personId].name) : e.name;
+            if (nm) manualNames.add(normName(nm));
+          } else openIdx.push(i);
+        }
+        const pool = members.filter((m) => !manualNames.has(normName(m.name)));
+        const assigned = assignMembersToSlots(openIdx.map((i) => eff[i]), pool);
+
+        for (let k = 0; k < openIdx.length; k += 1) {
+          const i = openIdx[k]; const m = assigned[k];
+          if (m) {
+            const lib = bestLibraryMatch(m.name, libEntries); // folder photo wins over the PCO headshot
+            const file = lib && lib.file ? lib.file : await cachePcoPhoto(m.personId, m.photoUrl);
+            board[String(i)] = { pco: { name: m.name, file, birthday: m.birthday || '', personId: m.personId } };
+          } else if (board[String(i)] && board[String(i)].pco) {
+            delete board[String(i)]; // was synced, no longer on the plan
+          }
+        }
+        saveBoard();
+        latest.reachable = true; latest.lastError = ''; latest.lastFetched = Date.now();
+        log(`synced ${members.length} scheduled from ${plan.dates || plan.id}`);
+        } // end else (plan found)
+        } // end if (Planning Center configured)
+      } catch (err) {
+        latest.reachable = false; latest.lastError = err?.message || String(err);
+        log(`sync failed: ${err?.message || err}`);
+      } finally {
+        syncing = false;
+        renderBoard(); broadcast();
+      }
+    }
+
+    const heartbeat = setInterval(() => { for (const res of streams) { try { res.write(': ping\n\n'); } catch { streams.delete(res); } } }, HEARTBEAT_MS);
+    heartbeat.unref?.();
+    // Repaint on a slow timer so a birthday week (Wed→Tue) rolling over lights up unattended.
+    celebrateTimer = setInterval(() => { if (!stopped) rebuildLocal(); }, 15 * 60 * 1000);
+    celebrateTimer.unref?.();
+    // A Drive folder can't be fs.watched — re-import it on a slow timer so photos added/removed
+    // in Drive show up without a manual Sync.
+    drivePollTimer = setInterval(() => {
+      if (stopped || !parseDriveFolderId(photoFolder)) return;
+      syncPhotos().then((ch) => { if (ch) rebuildLocal(); }).catch(() => {});
+    }, 5 * 60 * 1000);
+    drivePollTimer.unref?.();
+
+    if (pco.configured && serviceTypeId) log('ready — press Sync to load the plan from Planning Center');
+    else log('manual board (add Planning Center credentials + a service type in /admin to enable Sync)');
+    rebuildLocal(); // paint the saved board immediately
+    startWatch();   // local folders keep in sync via fs.watch (Drive folders are polled)
+    syncPhotos().then((ch) => { if (ch) rebuildLocal(); }).catch((err) => log(`initial photo import failed: ${err?.message || err}`));
+
+    current = {
+      streams, getLatest: () => latest, pco, listPlans, photoDir,
+      library, board, saveLibrary, saveBoard, rebuildLocal, refresh: () => syncNow(), slots,
+      photoUrlFor, libraryList,
+      setChoir, choirOn: () => choirOn,
+    };
+
+    return {
+      stop() {
+        stopped = true; if (celebrateTimer) clearInterval(celebrateTimer); if (drivePollTimer) clearInterval(drivePollTimer); clearInterval(heartbeat);
+        if (watcher) { try { watcher.close(); } catch { /* gone */ } watcher = null; }
+        if (watchDebounce) clearTimeout(watchDebounce);
+        for (const res of streams) { try { res.end(); } catch { /* gone */ } }
+        streams.clear(); if (current && current.streams === streams) current = null;
+      },
+      health() {
+        if (!pco.configured || !serviceTypeId) return { status: 'ok', message: 'Manual board (add Planning Center to enable Sync)' };
+        if (latest.lastError) return { status: 'error', message: latest.lastError };
+        if (latest.reachable) return { status: 'ok', message: latest.plan?.dates ? `Synced: ${latest.plan.dates}` : 'Synced' };
+        return { status: 'ok', message: 'Ready — press Sync to load the plan' };
+      },
+    };
+  },
+
+  routes({ log }) {
+    // Read an image request body (raw bytes) with a size cap.
+    function readBody(req, cb) {
+      const chunks = []; let size = 0; let bad = false;
+      req.on('data', (c) => { size += c.length; if (size > MAX_UPLOAD) { bad = true; req.destroy(); } else chunks.push(c); });
+      req.on('end', () => cb(bad ? null : Buffer.concat(chunks)));
+      req.on('error', () => cb(null));
+    }
+
+    return {
+      'GET /state': (req, res) => json(res, 200, { state: current ? current.getLatest() : null }),
+
+      'GET /stream': (req, res) => {
+        res.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-cache, no-transform', Connection: 'keep-alive', 'X-Accel-Buffering': 'no' });
+        res.write('retry: 3000\n\n');
+        res.write(`event: state\ndata: ${JSON.stringify(current ? current.getLatest() : null)}\n\n`);
+        if (!current) return void res.end();
+        try { req.socket.setKeepAlive(true, 15000); } catch { /* gone */ }
+        current.streams.add(res);
+        req.on('close', () => current && current.streams.delete(res));
+      },
+
+      'GET /library': (req, res) => json(res, 200, { people: current ? current.libraryList() : [] }),
+
+      // Update a library entry: ?name=&birthday= and/or a replacement image body. /library/<id>/delete removes it.
+      'POST /library/*': (req, res) => {
+        if (!current) return json(res, 503, { error: 'Module not running.' });
+        const rest = decodeURIComponent(req.wildcard || '').replace(/^\/+/, '');
+        const del = /\/delete$/.test(rest);
+        const id = rest.replace(/\/delete$/, '').trim();
+        const entry = current.library[id];
+        if (!entry) return json(res, 404, { error: 'No such library photo.' });
+        if (del) {
+          if (entry.file) { try { fs.unlinkSync(path.join(current.photoDir, entry.file)); } catch { /* ignore */ } }
+          delete current.library[id];
+          for (const [slot, v] of Object.entries(current.board)) if (v && v.personId === id) delete current.board[slot];
+          current.saveLibrary(); current.saveBoard(); current.rebuildLocal();
+          return json(res, 200, { ok: true });
+        }
+        const q = new URLSearchParams(req.search || '');
+        readBody(req, (buf) => {
+          if (q.has('name')) entry.name = String(q.get('name') || '').trim();
+          if (q.has('birthday')) entry.birthday = birthdayMmdd(q.get('birthday'));
+          if (buf && buf.length) {
+            if (entry.file) { try { fs.unlinkSync(path.join(current.photoDir, entry.file)); } catch { /* ignore */ } }
+            const file = `lib-${id}.${extFromContentType(req.headers['content-type'])}`;
+            try { fs.writeFileSync(path.join(current.photoDir, file), buf); entry.file = file; } catch (err) { return json(res, 500, { error: `write failed: ${err?.message || err}` }); }
+          }
+          current.saveLibrary(); current.rebuildLocal();
+          json(res, 200, { ok: true });
+        });
+      },
+
+      // Toggle the extra CHOIR slot on/off (?on=1|0, or omit to flip). Shared across all screens.
+      'POST /choir': (req, res) => {
+        if (!current) return json(res, 503, { error: 'Module not running.' });
+        const p = new URLSearchParams(req.search || '');
+        const on = p.has('on') ? (p.get('on') === '1' || p.get('on') === 'true') : !current.choirOn();
+        current.setChoir(on);
+        json(res, 200, { ok: true, choir: on });
+      },
+
+      // Move (or swap) one slot's occupant to another slot: ?from=<i>&to=<j>.
+      'POST /move': (req, res) => {
+        if (!current) return json(res, 503, { error: 'Module not running.' });
+        const p = new URLSearchParams(req.search || '');
+        const from = String(p.get('from') || ''); const to = String(p.get('to') || '');
+        if (!/^\d+$/.test(from) || !/^\d+$/.test(to) || from === to) return json(res, 400, { error: 'Bad move.' });
+        const a = current.board[from]; const b = current.board[to];
+        if (a === undefined) delete current.board[to]; else current.board[to] = a;
+        if (b === undefined) delete current.board[from]; else current.board[from] = b;
+        current.saveBoard(); current.rebuildLocal();
+        json(res, 200, { ok: true });
+      },
+
+      // Place a library person in a slot: ?slot=<index>&personId=<id> (empty personId clears the slot).
+      'POST /assign': (req, res) => {
+        if (!current) return json(res, 503, { error: 'Module not running.' });
+        const q = new URLSearchParams(req.search || '');
+        const slot = String(q.get('slot') || '').trim();
+        const personId = String(q.get('personId') || '').trim();
+        if (!/^\d+$/.test(slot)) return json(res, 400, { error: 'Bad slot.' });
+        if (personId && !current.library[personId]) return json(res, 404, { error: 'No such library photo.' });
+        if (personId) current.board[slot] = { personId, name: '' };
+        else delete current.board[slot];
+        current.saveBoard(); current.rebuildLocal();
+        json(res, 200, { ok: true });
+      },
+
+      // Rename a slot's occupant, or make a name-only spot (no photo). /slot/<index>/clear empties it.
+      'POST /slot/*': (req, res) => {
+        if (!current) return json(res, 503, { error: 'Module not running.' });
+        const rest = decodeURIComponent(req.wildcard || '').replace(/^\/+/, '');
+        const clearing = /\/clear$/.test(rest);
+        const index = rest.replace(/\/(clear|name)$/, '').trim();
+        if (!/^\d+$/.test(index)) return json(res, 400, { error: 'Bad slot.' });
+        if (clearing) { delete current.board[index]; current.saveBoard(); current.rebuildLocal(); return json(res, 200, { ok: true }); }
+        const q = new URLSearchParams(req.search || '');
+        const name = String(q.get('name') || '').trim();
+        const existing = current.board[index] || { personId: '', name: '' };
+        existing.name = name;
+        if (!existing.personId && !name) delete current.board[index];
+        else current.board[index] = existing;
+        current.saveBoard(); current.rebuildLocal();
+        json(res, 200, { ok: true });
+      },
+
+      // Force an immediate Planning Center refresh (the "Sync" button). Auto-fill also
+      // runs on its own timer; this just does it now.
+      'POST /sync': (req, res) => {
+        if (!current) return json(res, 503, { error: 'Module not running.' });
+        current.refresh(); // scans the photos folder + pulls the plan if Planning Center is configured
+        json(res, 200, { ok: true });
+      },
+
+      'GET /people': (req, res) => {
+        const state = current ? current.getLatest() : null;
+        const options = [{ value: '', label: 'Off' }];
+        for (const slot of state?.slots || []) if (slot.person && slot.person.name) options.push({ value: String(slot.index), label: slot.person.name });
+        json(res, 200, { options });
+      },
+
+      'GET /photo/*': (req, res) => {
+        if (!current) return void res.writeHead(404).end();
+        const name = path.basename(decodeURIComponent(req.wildcard || '').replace(/^\/+/, ''));
+        if (!name || name.includes('..')) return void res.writeHead(400).end();
+        fs.readFile(path.join(current.photoDir, name), (err, buf) => {
+          if (err) return void res.writeHead(404).end();
+          res.writeHead(200, { 'Content-Type': contentTypeForFile(name), 'Cache-Control': 'public, max-age=60' });
+          res.end(buf);
+        });
+      },
+
+      'GET /service-types': async (req, res) => {
+        if (!current) return json(res, 503, { options: [], error: 'Module not running.' });
+        if (!current.pco.configured) return json(res, 200, { options: [], error: 'No Planning Center credentials yet.' });
+        try {
+          const [folderBody, stBody] = await Promise.all([current.pco.getAll(`${SERVICES}/folders`), current.pco.getAll(`${SERVICES}/service_types`)]);
+          const folders = new Map();
+          for (const f of folderBody.data || []) folders.set(String(f.id), { name: String(f.attributes?.name || 'Folder'), parentId: f.relationships?.parent?.data?.id ? String(f.relationships.parent.data.id) : '' });
+          const pathOf = (parentId) => { const names = []; let id = parentId; const seen = new Set(); while (id && folders.has(id) && !seen.has(id)) { seen.add(id); names.unshift(folders.get(id).name); id = folders.get(id).parentId; } return names.join(' › '); };
+          const options = (stBody.data || []).map((st) => ({ value: String(st.id), label: String(st.attributes?.name || 'Service type'), group: pathOf(st.relationships?.parent?.data?.id ? String(st.relationships.parent.data.id) : '') })).sort((a, b) => a.group.localeCompare(b.group) || a.label.localeCompare(b.label));
+          json(res, 200, { options });
+        } catch (err) { log(`service type list failed: ${err?.message || err}`); json(res, err?.status === 401 ? 401 : 502, { options: [], error: err?.message || String(err) }); }
+      },
+
+      'GET /plans': async (req, res) => {
+        if (!current) return json(res, 503, { options: [] });
+        const params = new URLSearchParams(req.search || '');
+        const stId = String(params.get('serviceTypeId') || '').trim();
+        const auto = { value: '', label: 'Automatic — today\'s plan, else the next upcoming' };
+        if (!current.pco.configured || !stId) return json(res, 200, { options: [auto] });
+        try {
+          const plans = await current.listPlans(stId); const now = Date.now();
+          const ordered = [...plans.filter((p) => p.sortDate >= now - 12 * 3600000).sort((a, b) => a.sortDate - b.sortDate), ...plans.filter((p) => p.sortDate < now - 12 * 3600000).sort((a, b) => b.sortDate - a.sortDate)];
+          json(res, 200, { options: [auto, ...ordered.map((p) => ({ value: p.id, label: [p.dates, p.title].filter(Boolean).join(' — ') || p.id }))] });
+        } catch (err) { json(res, 502, { options: [auto], error: err?.message || String(err) }); }
+      },
+    };
+  },
+};

modules/band-lineup/style.css

@@ -0,0 +1,232 @@
+/* Band Lineup — scoped to the tile, themed only through the shell's variables. */
+
+[data-module="band-lineup"] .bl-board {
+  height: 100%;
+  overflow: hidden;
+  display: grid;
+  grid-template-columns: repeat(var(--bl-cols, 7), minmax(0, 1fr));
+  grid-template-rows: repeat(var(--bl-rows, 2), minmax(0, 1fr));
+  gap: 6px;
+  padding: 6px;
+}
+
+[data-module="band-lineup"] .bl-message {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  color: var(--muted);
+  padding: 16px;
+  font-size: 0.95em;
+}
+
+[data-module="band-lineup"] .bl-slot {
+  min-width: 0;
+  min-height: 0;
+}
+
+[data-module="band-lineup"] .bl-tile {
+  display: flex;
+  flex-direction: column;
+  border-radius: 10px;
+  overflow: hidden;
+  background: var(--panel);
+  border: 1px solid var(--border);
+  height: 100%;
+  position: relative;
+}
+
+[data-module="band-lineup"] .bl-photo {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+  overflow: hidden;
+  background: color-mix(in srgb, var(--bg) 70%, black);
+}
+
+[data-module="band-lineup"] .bl-img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  object-position: center top;
+  display: block;
+  transition: transform 0.12s ease-out;
+  will-change: transform;
+}
+
+[data-module="band-lineup"] .bl-initials {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 2.4em;
+  font-weight: 800;
+  color: color-mix(in srgb, var(--muted) 70%, transparent);
+  letter-spacing: 0.04em;
+}
+
+[data-module="band-lineup"] .bl-name {
+  position: absolute;
+  top: 6px;
+  left: 6px;
+  right: 6px;
+  max-width: calc(100% - 12px);
+  padding: 3px 7px;
+  border-radius: 6px;
+  background: color-mix(in srgb, var(--bg) 82%, transparent);
+  color: var(--text);
+  font-size: 0.74em;
+  font-weight: 700;
+  line-height: 1.12;
+  z-index: 5;
+  /* Show the whole name — wrap onto more lines rather than clipping with an ellipsis. */
+  white-space: normal;
+  overflow-wrap: break-word;
+  word-break: break-word;
+  hyphens: auto;
+}
+
+[data-module="band-lineup"] .bl-label {
+  padding: 5px 6px;
+  font-size: 0.72em;
+  font-weight: 600;
+  text-align: center;
+  color: var(--text);
+  background: color-mix(in srgb, var(--bg) 60%, transparent);
+  border-top: 1px solid var(--border);
+  min-height: 1.6em;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  word-break: break-word;
+}
+
+[data-module="band-lineup"] .bl-empty {
+  border-style: dashed;
+  opacity: 0.55;
+}
+[data-module="band-lineup"] .bl-empty .bl-label {
+  background: transparent;
+  border-top: none;
+  margin: auto;
+  color: var(--muted);
+}
+
+/* ---- Birthday effects (confetti canvas + gold glow ring) ---- */
+[data-module="band-lineup"] .bl-confetti {
+  position: absolute;
+  inset: 0;
+  z-index: 3;
+  pointer-events: none;
+}
+[data-module="band-lineup"] .bl-birthday-subtle {
+  animation: bl-glow-subtle 3.4s ease-in-out infinite;
+}
+[data-module="band-lineup"] .bl-birthday-full {
+  animation: bl-glow-full 2.2s ease-in-out infinite;
+}
+@keyframes bl-glow-subtle {
+  0%, 100% { box-shadow: inset 0 0 0 2px color-mix(in srgb, var(--accent) 55%, transparent), 0 0 14px color-mix(in srgb, var(--accent) 20%, transparent); }
+  50% { box-shadow: inset 0 0 0 2px var(--accent), 0 0 20px color-mix(in srgb, var(--accent) 34%, transparent); }
+}
+@keyframes bl-glow-full {
+  0%, 100% { box-shadow: inset 0 0 0 3px color-mix(in srgb, var(--accent) 80%, transparent), 0 0 20px color-mix(in srgb, var(--accent) 42%, transparent); }
+  50% { box-shadow: inset 0 0 0 3px var(--accent), 0 0 34px color-mix(in srgb, var(--accent) 66%, transparent); }
+}
+
+/* ---- Editor (Edit button): board drop-targets + uploaded-photo library ---- */
+[data-module="band-lineup"] .bl-btn {
+  border: 1px solid var(--border);
+  background: var(--panel);
+  color: var(--text);
+  border-radius: 6px;
+  padding: 5px 11px;
+  font: inherit;
+  font-size: 0.82em;
+  cursor: pointer;
+}
+[data-module="band-lineup"] .bl-btn.primary { background: var(--accent); color: var(--accent-text); border-color: transparent; }
+[data-module="band-lineup"] .bl-btn:hover { border-color: var(--accent); }
+
+[data-module="band-lineup"] .bl-editor {
+  position: absolute;
+  inset: 0;
+  z-index: 20;
+  display: flex;
+  flex-direction: column;
+  background: var(--bg);
+}
+[data-module="band-lineup"] .bl-editor-bar {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border-bottom: 1px solid var(--border);
+  flex: 0 0 auto;
+}
+[data-module="band-lineup"] .bl-editor-bar b { color: var(--text); }
+[data-module="band-lineup"] .bl-editor-spacer { flex: 1; }
+[data-module="band-lineup"] .bl-folder { display: flex; align-items: center; gap: 6px; min-width: 0; }
+[data-module="band-lineup"] .bl-folder-path { font-size: 0.72em; color: var(--muted); max-width: 240px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+[data-module="band-lineup"] .bl-editor-body { flex: 1; min-height: 0; overflow: auto; padding: 10px; }
+
+[data-module="band-lineup"] .bl-edit-board {
+  display: grid;
+  grid-template-columns: repeat(var(--bl-cols, 7), minmax(0, 1fr));
+  gap: 6px;
+  margin-bottom: 12px;
+}
+[data-module="band-lineup"] .bl-edit-slot {
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  overflow: hidden;
+  background: var(--panel);
+  display: flex;
+  flex-direction: column;
+}
+[data-module="band-lineup"] .bl-edit-slot.bl-drop-over { border-color: var(--accent); box-shadow: inset 0 0 0 2px var(--accent); }
+[data-module="band-lineup"] .bl-edit-photo { position: relative; aspect-ratio: 3 / 4; background: color-mix(in srgb, var(--bg) 70%, black); overflow: hidden; }
+[data-module="band-lineup"] .bl-edit-photo .bl-img { width: 100%; height: 100%; object-fit: cover; object-position: center top; }
+[data-module="band-lineup"] .bl-edit-drop {
+  position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+  color: var(--muted); font-size: 1.6em; border: 1px dashed var(--border);
+}
+[data-module="band-lineup"] .bl-edit-namerow { display: flex; align-items: center; gap: 2px; padding: 2px; }
+[data-module="band-lineup"] .bl-edit-name {
+  flex: 1; min-width: 0; text-align: left; background: transparent; border: 0;
+  color: var(--text); font: inherit; font-size: 0.72em; font-weight: 600; padding: 3px 4px;
+  cursor: pointer; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; border-radius: 4px;
+}
+[data-module="band-lineup"] .bl-edit-name:hover { background: color-mix(in srgb, var(--accent) 16%, transparent); }
+[data-module="band-lineup"] .bl-edit-clear {
+  flex: 0 0 auto; width: 20px; height: 20px; border: 0; border-radius: 4px;
+  background: color-mix(in srgb, var(--danger) 18%, transparent); color: var(--danger); cursor: pointer; font-size: 0.9em; line-height: 1;
+}
+[data-module="band-lineup"] .bl-edit-label { padding: 3px 5px 5px; font-size: 0.64em; color: var(--muted); text-align: center; border-top: 1px solid var(--border); word-break: break-word; }
+
+[data-module="band-lineup"] .bl-library {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(78px, 1fr));
+  gap: 6px;
+  border-top: 1px solid var(--border);
+  padding-top: 10px;
+}
+[data-module="band-lineup"] .bl-lib-empty { grid-column: 1 / -1; color: var(--muted); font-size: 0.85em; padding: 10px 2px; }
+[data-module="band-lineup"] .bl-lib-item {
+  position: relative; border: 1px solid var(--border); border-radius: 8px; overflow: hidden;
+  background: var(--panel); cursor: grab; display: flex; flex-direction: column;
+}
+[data-module="band-lineup"] .bl-lib-item:active { cursor: grabbing; }
+[data-module="band-lineup"] .bl-lib-selected { border-color: var(--accent); box-shadow: 0 0 0 2px var(--accent); }
+[data-module="band-lineup"] .bl-lib-photo { position: relative; aspect-ratio: 3 / 4; background: color-mix(in srgb, var(--bg) 70%, black); overflow: hidden; }
+[data-module="band-lineup"] .bl-lib-img { width: 100%; height: 100%; object-fit: cover; object-position: center top; pointer-events: none; }
+[data-module="band-lineup"] .bl-lib-name {
+  border: 0; background: transparent; color: var(--text); font: inherit; font-size: 0.68em; font-weight: 600;
+  padding: 3px 4px; text-align: center; cursor: pointer; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+[data-module="band-lineup"] .bl-lib-del {
+  position: absolute; top: 3px; right: 3px; width: 18px; height: 18px; border: 0; border-radius: 4px;
+  background: color-mix(in srgb, var(--bg) 60%, transparent); color: var(--text); cursor: pointer; font-size: 0.85em; line-height: 1;
+}
+[data-module="band-lineup"] .bl-lib-del:hover { background: var(--danger); color: #fff; }

modules/pco-plan/matching.js

@@ -2,10 +2,12 @@
 
 /**
  * Title matching for the PCO Plan module — the one answer to "is this
- * ProPresenter document that Planning Center thing?", used twice:
+ * ProPresenter document that Planning Center thing?", used three ways:
  *
  *   - mapping the document ProPresenter has live to a plan item (the
- *     highlight and the item runtimes), and
+ *     highlight and the item runtimes) — placeDocument(), below,
+ *   - recognising the message document, which is named after the sermon
+ *     and never after its plan item — the message rule, below, and
  *   - recognising the documents an admin picked as the service start / end
  *     cues (see service-timing.js).
  *
@@ -82,4 +84,176 @@ function isCue(liveName, cueDocument) {
   return Boolean(cueDocument) && similarity(liveName, cueDocument) >= TRIGGER_THRESHOLD;
 }
 
-module.exports = { MATCH_THRESHOLD, TRIGGER_THRESHOLD, cleanTitle, normalize, similarity, isCue };
+/* ── the message rule ──────────────────────────────────────────────────
+   A sermon's ProPresenter document is named after the sermon, never after
+   the plan item that stands for it ("Message", "Resi Message"), so no name
+   comparison can place it — and the previous song stayed "current" through
+   a whole message. What the document's name does carry is the plan's own
+   identity. Waters names them "YYMMDD Series Title - Part #": the plan's
+   date, its series title and its title. A live document that reads like
+   the plan is the plan's message, and lands on the plan's message item,
+   however that item happens to be titled. */
+
+const MESSAGE_WORDS = /\b(message|sermon|teaching|homily)\b/i;
+const MESSAGE_WORD_ONLY = /^\s*(message|sermon|teaching|homily)\s*$/i;
+/** Undated, the name must read like "Series Title Part #" at least this closely… */
+const MESSAGE_THRESHOLD = 0.75;
+/** …dated with this plan's date, it need only resemble the series or the title. */
+const DATED_MESSAGE_THRESHOLD = 0.6;
+
+/** The leading "YYMMDD" / "YYYYMMDD" of a document name as a calendar day, or null. */
+function leadingDateCode(raw) {
+  const m = /^\s*(\d{8}|\d{6})(?!\d)/.exec(String(raw || ''));
+  if (!m) return null;
+  const code = m[1];
+  const y = code.length === 8 ? Number(code.slice(0, 4)) : 2000 + Number(code.slice(0, 2));
+  const mo = Number(code.slice(-4, -2));
+  const d = Number(code.slice(-2));
+  if (mo < 1 || mo > 12 || d < 1 || d > 31) return null;
+  return { y, m: mo, d };
+}
+
+/** The local calendar day of an epoch-ms instant, in the same shape. */
+function dayOf(ms) {
+  const t = new Date(Number(ms));
+  if (!Number.isFinite(t.getTime())) return null;
+  return { y: t.getFullYear(), m: t.getMonth() + 1, d: t.getDate() };
+}
+
+function sameDay(a, b) {
+  return Boolean(a && b) && a.y === b.y && a.m === b.m && a.d === b.d;
+}
+
+/**
+ * Does this live document read like the plan itself — "260927 Where is Your
+ * Faith? - Part 6" for the plan "Where is Your Faith?" / "Part 6" dated
+ * 27 Sept 2026? Returns { score, dated } or null.
+ *
+ * A date code naming another day is a firm no: last week's sermon is not
+ * this plan's message. A date code naming the plan's day is strong evidence,
+ * so the rest need only resemble the series or the title. Without a date
+ * the name must read like series + title together — and carry the title
+ * when the plan has both, so a series bumper ("Where is Your Faith?") is
+ * not taken for the sermon.
+ */
+function messageDocumentScore(name, plan) {
+  const series = String(plan?.seriesTitle || '').trim();
+  const title = String(plan?.title || '').trim();
+  if (!series && !title) return null;
+  const code = leadingDateCode(name);
+  const planDay = plan?.sortDate ? dayOf(plan.sortDate) : null;
+  if (code && planDay && !sameDay(code, planDay)) return null;
+  const dated = Boolean(code && planDay);
+  const full = [series, title].filter(Boolean).join(' ');
+  const fullScore = similarity(name, full);
+  if (dated) {
+    const score = Math.max(fullScore, series ? similarity(name, series) : 0, title ? similarity(name, title) : 0);
+    return score >= DATED_MESSAGE_THRESHOLD ? { score, dated: true } : null;
+  }
+  if (fullScore < MESSAGE_THRESHOLD) return null;
+  if (series && title && similarity(name, title) < DATED_MESSAGE_THRESHOLD) return null;
+  return { score: fullScore, dated: false };
+}
+
+/**
+ * The plan item that stands for the message: an item titled with the word
+ * ("Message", "Resi Message" — a bare "Message" first), else the first item
+ * under a header so titled (a "Sermon" section whose one item is the sermon's
+ * own title). Null when the plan has no such slot.
+ */
+function messageItemOf(items) {
+  let best = null;
+  let inSection = false;
+  for (const it of Array.isArray(items) ? items : []) {
+    if (!it) continue;
+    const title = String(it.title || '');
+    if (it.itemType === 'header') {
+      inSection = MESSAGE_WORDS.test(title);
+      continue;
+    }
+    const rank = MESSAGE_WORD_ONLY.test(title) ? 3 : MESSAGE_WORDS.test(title) ? 2 : inSection ? 1 : 0;
+    if (rank && (!best || rank > best.rank)) best = { item: it, rank };
+    if (rank === 3) break;
+  }
+  return best ? best.item : null;
+}
+
+/**
+ * Does ProPresenter's playlist mirror the plan item for item? ProPresenter
+ * builds a Planning Center playlist that way — every plan item, headers
+ * included, each flagged as PCO — until an operator adds something of their
+ * own (a song tag, say), which shifts every position after it. Same length,
+ * headers in the same places and every item PCO-flagged is the test.
+ */
+function playlistMirrorsPlan(ppItems, items) {
+  if (!Array.isArray(ppItems) || !Array.isArray(items) || !items.length || ppItems.length !== items.length) return false;
+  return ppItems.every((p, i) => Boolean(p?.isPco) && (p?.type === 'header') === (items[i]?.itemType === 'header'));
+}
+
+/** Best plan item by title, the ones ahead of the current item winning ties. */
+function bestByName(name, items, all, ctx) {
+  const currentIdx = items.findIndex((it) => it.id === ctx?.currentItemId);
+  const hint = ctx?.hint;
+  const wanted = hint && hint.mirror && Number.isInteger(hint.index) && hint.index >= 0 ? all[hint.index] : null;
+  let best = null;
+  for (let i = 0; i < items.length; i += 1) {
+    const item = items[i];
+    const score = Math.max(similarity(name, item.title), item.song ? similarity(name, item.song.title) : 0);
+    if (score < MATCH_THRESHOLD) continue;
+    // Distance ahead of the current item (wrapping so items behind rank last).
+    const dist = currentIdx < 0 ? i : (i - currentIdx + items.length) % items.length;
+    const atPosition = Boolean(wanted && item.id === wanted.id);
+    const candidate = { item, score, dist, atPosition };
+    if (!best || score > best.score + 0.001) {
+      best = candidate;
+      continue;
+    }
+    if (Math.abs(score - best.score) > 0.001) continue;
+    if ((atPosition && !best.atPosition) || (atPosition === best.atPosition && dist < best.dist)) best = candidate;
+  }
+  return best ? { item: best.item, score: best.score, via: 'name' } : null;
+}
+
+/**
+ * Where a live ProPresenter document sits in the plan: { item, score, via }
+ * or null. `ctx` is { items, plan, currentItemId, hint }; `hint` (optional)
+ * is { index, mirror } — the document's position in the ProPresenter
+ * playlist and whether that playlist mirrors the plan (playlistMirrorsPlan).
+ *
+ * By name first: the item (or song) title most like the document's name,
+ * the ones ahead of the current item winning ties — a near miss lands on the
+ * right row. Then the message rule: a document that reads like the plan
+ * itself lands on the plan's message item. It overrides a name hit that is
+ * anything short of identical — a song called "Faith" must not catch
+ * "260927 Where is Your Faith? - Part 6" — outright when the document is
+ * dated with the plan's day, and when it reads better otherwise. Position
+ * is never a match on its own: it only breaks a tie between equally good
+ * names, and only while the playlist mirrors the plan.
+ */
+function placeDocument(name, ctx) {
+  const all = Array.isArray(ctx?.items) ? ctx.items : [];
+  const items = all.filter((it) => it && it.itemType !== 'header');
+  if (!items.length) return null;
+  const byName = bestByName(name, items, all, ctx);
+  const asMessage = messageDocumentScore(name, ctx?.plan);
+  const messageItem = asMessage ? messageItemOf(all) : null;
+  if (messageItem && (!byName || (byName.score < 0.999 && (asMessage.dated || asMessage.score > byName.score)))) {
+    return { item: messageItem, score: asMessage.score, via: asMessage.dated ? 'message document, dated' : 'message document' };
+  }
+  return byName;
+}
+
+module.exports = {
+  MATCH_THRESHOLD,
+  TRIGGER_THRESHOLD,
+  MESSAGE_THRESHOLD,
+  cleanTitle,
+  normalize,
+  similarity,
+  isCue,
+  leadingDateCode,
+  messageDocumentScore,
+  messageItemOf,
+  playlistMirrorsPlan,
+  placeDocument,
+};

modules/pco-plan/matching.test.js

@@ -0,0 +1,280 @@
+'use strict';
+
+/**
+ * Unit tests for the PCO Plan module's document matching — placing what
+ * ProPresenter has live onto a plan item, and the message rule.
+ *
+ *   node modules/pco-plan/matching.test.js
+ *
+ * Plain Node, no dependencies; exits non-zero on the first failure. The two
+ * plans are the campuses' real 27 Sept 2026 plans and ProPresenter playlists
+ * as they stood on 22 Sept, so the expectations read like a Sunday would.
+ */
+
+const assert = require('assert');
+const {
+  MESSAGE_THRESHOLD,
+  leadingDateCode,
+  messageDocumentScore,
+  messageItemOf,
+  playlistMirrorsPlan,
+  placeDocument,
+} = require('./matching');
+
+let passed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed += 1;
+    console.log(`  ok   ${name}`);
+  } catch (err) {
+    console.log(`  FAIL ${name}\n       ${err.message}`);
+    process.exitCode = 1;
+    throw err;
+  }
+}
+
+const SUNDAY = new Date(2026, 8, 27, 9, 30).getTime(); // 27 Sept 2026, 9:30 local — the plan's sort date
+const PLAN = { id: '91274523', title: 'Part 6', seriesTitle: 'Where is Your Faith?', sortDate: SUNDAY };
+
+const header = (id, title) => ({ id, itemType: 'header', title, song: null });
+const item = (id, title, itemType = 'item', song = null) => ({ id, itemType, title, song: song ? { title: song } : null });
+const pp = (name, type = 'presentation', isPco = true) => ({ name, type, isPco, isHidden: false });
+
+// North Attleboro — the message is an item called "Message", linked in
+// ProPresenter to the bumper video; the sermon slides are their own document.
+const NA = [
+  header('h0', 'Doors Open'),
+  item('1', 'Preservice'),
+  item('2', '5 Minute Countdown', 'media'),
+  item('3', 'MC Announcements', 'media'),
+  header('h4', 'Worship'),
+  item('5', 'Call To Worship', 'media'),
+  item('6', 'Alleluia', 'song', 'Alleluia'),
+  item('7', 'What a God', 'song', 'What a God'),
+  item('8', 'Baptisms', 'media'),
+  item('9', 'Promised Land', 'song', 'Promised Land'),
+  item('10', 'Be Praised', 'song', 'Be Praised'),
+  header('h11', 'Message'),
+  item('12', 'Message'),
+  item('13', 'Standing Salvation Moment', 'media'),
+  header('h14', 'Closing'),
+  item('15', 'Postservice', 'song', '-Postservice'),
+];
+const NA_PP = [
+  pp('Doors Open', 'header'), pp('Preservice'), pp('5 Minute Countdown'), pp('MC Announcements'),
+  pp('Worship', 'header'), pp('Call To Worship'), pp('Alleluia - [ Full ]'), pp('What a God - [ Full ]'),
+  pp('Baptisms'), pp('Promised Land - [ Full ]'), pp('Be Praised - [ Full ]'),
+  pp('Message', 'header'), pp('Message Bumper'), pp('Standing Salvation Moment'),
+  pp('Closing', 'header'), pp('Postservice'),
+];
+
+// Apollo Beach — the message is the media item "Resi Message".
+const AB = [
+  item('0', 'Pre Service Meeting', 'media'),
+  header('h1', 'Doors Open'),
+  item('2', 'Pre Service', 'media'),
+  item('3', '5 Minute Countdown', 'media'),
+  item('4', 'MC Announcements', 'media'),
+  header('h5', 'Worship'),
+  item('6', 'Call To Worship', 'media'),
+  item('7', 'Alleluia', 'song', 'Alleluia'),
+  item('8', 'What a God', 'song', 'What a God'),
+  item('9', 'The Blood', 'song', 'The Blood'),
+  item('10', 'Be Praised (feat. Kymberli Joye)', 'song', 'Be Praised'),
+  header('h11', 'Message'),
+  item('12', 'Resi Message', 'media'),
+  item('13', 'Standing Salvation Moment', 'media'),
+  header('h14', 'Closing'),
+  item('15', 'Post Service', 'media'),
+];
+
+const SERMON = '260927 Where is Your Faith? - Part 6';
+const place = (name, items, extra = {}) => placeDocument(name, { items, plan: PLAN, currentItemId: '', ...extra });
+const titleOf = (hit) => (hit ? hit.item.title : null);
+
+console.log('date codes');
+
+test('YYMMDD and YYYYMMDD lead a document name; anything else is not a date', () => {
+  assert.deepStrictEqual(leadingDateCode(SERMON), { y: 2026, m: 9, d: 27 });
+  assert.deepStrictEqual(leadingDateCode('20260927 Where is Your Faith? - Part 6'), { y: 2026, m: 9, d: 27 });
+  assert.strictEqual(leadingDateCode('9-27-26 Where is Your Faith?'), null);
+  assert.strictEqual(leadingDateCode('1234567 seven digits'), null);
+  assert.strictEqual(leadingDateCode('261340 no such month'), null);
+  assert.strictEqual(leadingDateCode('Alleluia'), null);
+  assert.strictEqual(leadingDateCode(''), null);
+});
+
+console.log('the message rule');
+
+test('a document named like the plan, dated with its day, is the message', () => {
+  const hit = messageDocumentScore(SERMON, PLAN);
+  assert.ok(hit, 'recognised');
+  assert.strictEqual(hit.dated, true);
+  assert.strictEqual(hit.score, 1);
+});
+
+test("last week's document is not this plan's message", () => {
+  assert.strictEqual(messageDocumentScore('260920 Where is Your Faith? - Part 5', PLAN), null);
+  assert.strictEqual(messageDocumentScore('260920 Where is Your Faith? - Part 6', PLAN), null, 'even with the right part: the date names another day');
+});
+
+test('undated, series and part together still read as the message', () => {
+  const plain = messageDocumentScore('Where is Your Faith? - Part 6', PLAN);
+  assert.ok(plain && plain.dated === false && plain.score === 1);
+  const tagged = messageDocumentScore('Where Is Your Faith - Part 6 - [ Notes ]', PLAN);
+  assert.ok(tagged && tagged.score >= MESSAGE_THRESHOLD, 'tags and punctuation do not matter');
+});
+
+test('a series bumper is not the sermon', () => {
+  assert.strictEqual(messageDocumentScore('Where is Your Faith?', PLAN), null, 'the series alone, undated');
+  assert.strictEqual(messageDocumentScore('Where is Your Faith? Bumper', PLAN), null);
+});
+
+test("dated with the plan's day, the part alone is enough", () => {
+  const hit = messageDocumentScore('260927 Part 6', PLAN);
+  assert.ok(hit && hit.dated);
+});
+
+test('a dated document about something else is not the message', () => {
+  assert.strictEqual(messageDocumentScore('260927 Announcements', PLAN), null);
+  assert.strictEqual(messageDocumentScore('260927 Baptism Video', PLAN), null);
+});
+
+test('songs are not the message', () => {
+  assert.strictEqual(messageDocumentScore('What a God - [ Full ]', PLAN), null);
+  assert.strictEqual(messageDocumentScore('Alleluia', PLAN), null);
+  assert.strictEqual(messageDocumentScore('Message Bumper', PLAN), null);
+});
+
+test('a plan with neither series nor title has no message document', () => {
+  assert.strictEqual(messageDocumentScore(SERMON, { sortDate: SUNDAY }), null);
+  assert.strictEqual(messageDocumentScore(SERMON, null), null);
+});
+
+test('a plan without a date still recognises its own name', () => {
+  const hit = messageDocumentScore(SERMON, { title: 'Part 6', seriesTitle: 'Where is Your Faith?' });
+  assert.ok(hit && hit.dated === false && hit.score === 1);
+});
+
+console.log('the message item');
+
+test('an item called Message is the message item; so is Resi Message', () => {
+  assert.strictEqual(messageItemOf(NA).id, '12');
+  assert.strictEqual(messageItemOf(AB).id, '12');
+});
+
+test('a bare "Message" beats an item that only contains the word', () => {
+  const withBumper = [...NA.slice(0, 12), item('12a', 'Message Bumper', 'media'), ...NA.slice(12)];
+  assert.strictEqual(messageItemOf(withBumper).id, '12');
+  assert.strictEqual(messageItemOf([item('a', 'Message Bumper', 'media')]).id, 'a', 'alone, it is the slot');
+});
+
+test('under a Sermon header, the first item is the message whatever it is called', () => {
+  const plan = [header('h', 'Worship'), item('1', 'Alleluia', 'song', 'Alleluia'), header('s', 'Sermon'), item('2', 'Living Hope'), item('3', 'Response')];
+  assert.strictEqual(messageItemOf(plan).id, '2');
+});
+
+test('a plan without a message slot has none', () => {
+  assert.strictEqual(messageItemOf([header('h', 'Worship'), item('1', 'Alleluia', 'song', 'Alleluia')]), null);
+  assert.strictEqual(messageItemOf([header('m', 'Message')]), null, 'a header with nothing under it');
+  assert.strictEqual(messageItemOf([]), null);
+  assert.strictEqual(messageItemOf(null), null);
+});
+
+console.log('the playlist mirror');
+
+test("ProPresenter's Planning Center playlist mirrors the plan, headers and all", () => {
+  assert.strictEqual(playlistMirrorsPlan(NA_PP, NA), true);
+});
+
+test('an item the operator added, a header out of place or a non-PCO item breaks the mirror', () => {
+  const extra = [...NA_PP.slice(0, 10), pp('The Blood TAG'), ...NA_PP.slice(10)];
+  assert.strictEqual(playlistMirrorsPlan(extra, NA), false, 'a song tag shifts everything after it');
+  const shifted = [...NA_PP];
+  [shifted[3], shifted[4]] = [shifted[4], shifted[3]];
+  assert.strictEqual(playlistMirrorsPlan(shifted, NA), false);
+  const local = NA_PP.map((x, i) => (i === 8 ? pp('Baptisms', 'presentation', false) : x));
+  assert.strictEqual(playlistMirrorsPlan(local, NA), false);
+  assert.strictEqual(playlistMirrorsPlan([], []), false);
+  assert.strictEqual(playlistMirrorsPlan(null, NA), false);
+});
+
+console.log('placing what is live');
+
+test('songs and media land by name, tags and all', () => {
+  const god = place('What a God - [ Full ]', NA);
+  assert.strictEqual(titleOf(god), 'What a God');
+  assert.strictEqual(god.via, 'name');
+  assert.strictEqual(titleOf(place('Resi Message - [ MEDIA ]', AB)), 'Resi Message');
+  assert.strictEqual(titleOf(place('Greatly To Be Praised - [ Full ]', AB)), 'Be Praised (feat. Kymberli Joye)', 'by the song title');
+  assert.strictEqual(titleOf(place('Pre Service - [ Sunday ]', AB)), 'Pre Service');
+});
+
+test('the sermon document lands on the message item at both campuses', () => {
+  const na = place(SERMON, NA);
+  assert.strictEqual(titleOf(na), 'Message');
+  assert.strictEqual(na.via, 'message document, dated');
+  assert.strictEqual(titleOf(place(SERMON, AB)), 'Resi Message');
+  assert.strictEqual(place('Where is Your Faith? - Part 6', NA).via, 'message document', 'undated still lands, and says so');
+});
+
+test('the bumper lands on the message item too, by name', () => {
+  const hit = place('Message Bumper', NA);
+  assert.strictEqual(titleOf(hit), 'Message');
+  assert.strictEqual(hit.via, 'name');
+});
+
+test('a song called Faith does not catch the sermon', () => {
+  const trap = [...NA.slice(0, 11), item('f', 'Faith', 'song', 'Faith'), ...NA.slice(11)];
+  assert.strictEqual(titleOf(place('Faith - [ Full ]', trap)), 'Faith', 'the song itself still lands');
+  assert.strictEqual(titleOf(place(SERMON, trap)), 'Message', 'dated: the message wins outright');
+  assert.strictEqual(titleOf(place('Where is Your Faith? - Part 6', trap)), 'Message', 'undated: it reads better than the song');
+});
+
+test('an item titled exactly like the document wins over the message slot', () => {
+  const titled = [...NA.slice(0, 12), item('s', 'Where is Your Faith? - Part 6'), ...NA.slice(12)];
+  assert.strictEqual(place(SERMON, titled).item.id, 's');
+});
+
+test('a plan without a message slot leaves the sermon document unplaced', () => {
+  const noSlot = NA.filter((it) => it.id !== '12' && it.id !== 'h11');
+  assert.strictEqual(place(SERMON, noSlot), null);
+});
+
+test("an unplanned document, or last week's sermon, lands nowhere", () => {
+  assert.strictEqual(place('Offering Slide', NA), null);
+  assert.strictEqual(place('260920 Where is Your Faith? - Part 5', NA), null);
+});
+
+test('nothing to place on an empty plan', () => {
+  assert.strictEqual(place(SERMON, []), null);
+  assert.strictEqual(place(SERMON, [header('h', 'Message')]), null);
+});
+
+// The same song twice: a reprise after "What a God".
+const REPRISE = [...NA.slice(0, 8), item('6b', 'Alleluia', 'song', 'Alleluia'), ...NA.slice(8)];
+const REPRISE_PP = [...NA_PP.slice(0, 8), pp('Alleluia - [ Reprise ]'), ...NA_PP.slice(8)];
+
+test('a tie between equal names goes to the one ahead of the current item', () => {
+  assert.strictEqual(place('Alleluia - [ Full ]', REPRISE).item.id, '6', 'nothing current yet: the first');
+  assert.strictEqual(place('Alleluia - [ Full ]', REPRISE, { currentItemId: '7' }).item.id, '6b', 'after What a God: the reprise');
+  assert.strictEqual(place('Alleluia - [ Full ]', REPRISE, { currentItemId: '6b' }).item.id, '6b', 'the current one keeps a tie');
+});
+
+test('position breaks a tie only while the playlist mirrors the plan', () => {
+  const mirror = playlistMirrorsPlan(REPRISE_PP, REPRISE);
+  assert.strictEqual(mirror, true);
+  assert.strictEqual(place('Alleluia - [ Reprise ]', REPRISE, { hint: { index: 8, mirror } }).item.id, '6b');
+  assert.strictEqual(place('Alleluia - [ Full ]', REPRISE, { hint: { index: 6, mirror } }).item.id, '6');
+  assert.strictEqual(place('Alleluia - [ Full ]', REPRISE, { currentItemId: '7', hint: { index: 6, mirror } }).item.id, '6', 'position wins the tie over "ahead"');
+  assert.strictEqual(place('Alleluia - [ Reprise ]', REPRISE, { hint: { index: 8, mirror: false } }).item.id, '6', 'no mirror: back to "ahead"');
+});
+
+test('position never places a document on its own', () => {
+  const mirror = playlistMirrorsPlan(NA_PP, NA);
+  assert.strictEqual(place('Offering Slide', NA, { hint: { index: 8, mirror } }), null);
+  assert.strictEqual(titleOf(place('What a God - [ Full ]', NA, { hint: { index: 12, mirror } })), 'What a God', 'a wrong position cannot move a clear name');
+});
+
+console.log(`\n${passed} tests passed`);

modules/pco-plan/module.json

@@ -1,7 +1,7 @@
 {
   "id": "pco-plan",
   "name": "PCO Plan",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "proddash": ">=1.4.0",
   "description": "Order of service from Planning Center Services",
   "provides": [

modules/pco-plan/server.js

@@ -33,8 +33,12 @@
  * Following ProPresenter: instead of talking to ProPresenter a second time,
  * this module reads the propresenter-now-next module's own SSE feed over
  * loopback (/api/modules/propresenter-now-next/stream, on shell.port) and
- * matches the live presentation name to a plan item. Item start/end
- * timestamps are tracked here, once, so every tile agrees on the runtime.
+ * places the live document on a plan item (matching.js placeDocument): by
+ * name, or — for the sermon, whose document is named after the sermon and
+ * never after its plan item — by reading like the plan itself ("YYMMDD
+ * Series Title - Part #"), which lands it on the plan's message item. Item
+ * start/end timestamps are tracked here, once, so every tile agrees on the
+ * runtime.
  *
  * Service timing: a plan's services (9:00, 11:00…) take turns owning the
  * service clock — the rules live in service-timing.js. A service starts at
@@ -52,7 +56,7 @@ const http = require('http');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { MATCH_THRESHOLD, similarity } = require('./matching');
+const { placeDocument, messageItemOf, playlistMirrorsPlan } = require('./matching');
 const {
   MINUTE,
   serviceTimes,
@@ -434,6 +438,8 @@ module.exports = {
     let inFlight = null;
     let lastFrame = '';
     let lastTimersSig = '';
+    let lastMessageItemId = null;
+    let lastMatchError = '';
 
     /* — broadcasting — */
 
@@ -582,6 +588,7 @@ module.exports = {
       }
       state.plan = plan;
       state.items = items;
+      noteMessageItem(items);
       state.reachable = true;
       state.lastError = '';
       state.lastFetched = Date.now();
@@ -596,6 +603,17 @@ module.exports = {
       syncServiceSafe(Date.now(), null);
     }
 
+    /** Say, once per plan, which item a document named like the plan will land on. */
+    function noteMessageItem(items) {
+      const msg = messageItemOf(items);
+      const id = msg ? msg.id : '';
+      if (id === lastMessageItemId) return;
+      lastMessageItemId = id;
+      log(msg
+        ? `message item: "${msg.title}" — a live document named like this plan (its date, series and part) lands here`
+        : 'no message item in this plan — a document named like the plan has nowhere to land');
+    }
+
     /* — item note categories (a tile's "Item notes" → Categories switches) — */
 
     let noteCategories = { at: 0, options: [] }; // the last good answer from Planning Center
@@ -996,36 +1014,29 @@ module.exports = {
       };
       lastLiveName = keep.activeName || '';
       if (follow && keep.activeName) {
-        const hit = matchItem(keep.activeName);
+        const hit = matchItem(keep.activeName, hintFrom(lastView));
         state.live.matched = Boolean(hit);
         if (hit) {
           state.live.currentScore = hit.score;
-          startItem(hit.item.id);
+          startItem(hit.item.id, keep.activeName, hit);
         }
       }
     }
 
-    /** Best plan item for a live presentation name, preferring the ones ahead of us. */
-    function matchItem(name) {
-      const items = state.items.filter((it) => it.itemType !== 'header');
-      if (!items.length) return null;
-      const currentIdx = items.findIndex((it) => it.id === state.live.currentItemId);
-      let best = null;
-      for (let i = 0; i < items.length; i += 1) {
-        const item = items[i];
-        const score = Math.max(similarity(name, item.title), item.song ? similarity(name, item.song.title) : 0);
-        if (score < MATCH_THRESHOLD) continue;
-        // Distance ahead of the current item (wrapping so items behind rank last).
-        const dist = currentIdx < 0 ? i : (i - currentIdx + items.length) % items.length;
-        if (
-          !best
-          || score > best.score + 0.001
-          || (Math.abs(score - best.score) <= 0.001 && dist < best.dist)
-        ) {
-          best = { item, score, dist };
-        }
-      }
-      return best;
+    /**
+     * The plan item a live document stands for — { item, score, via } or
+     * null. The rules live in matching.js (placeDocument): by name, then the
+     * message rule for a document named like the plan itself; the playlist
+     * position only breaks ties, and only while the playlist mirrors the plan.
+     */
+    function matchItem(name, hint) {
+      return placeDocument(name, { items: state.items, plan: state.plan, currentItemId: state.live.currentItemId, hint });
+    }
+
+    /** The live item's place in ProPresenter's playlist, and whether that playlist mirrors the plan. */
+    function hintFrom(view) {
+      const index = Number.isInteger(view?.activeIndex) ? view.activeIndex : -1;
+      return { index, mirror: index >= 0 && playlistMirrorsPlan(view?.items, state.items) };
     }
 
     /** Remember a document ProPresenter put live, most recent first, for the admin selects. */
@@ -1077,6 +1088,7 @@ module.exports = {
     function applyLiveView(view) {
       lastView = view && typeof view === 'object' ? view : null;
       const live = state.live;
+      if (!live.available) log('following the ProPresenter module feed');
       live.available = true;
       live.reason = '';
       live.ppEnabled = Boolean(view?.enabled);
@@ -1095,23 +1107,40 @@ module.exports = {
         broadcast(); // reachability may have changed; the frame check keeps it quiet otherwise
         return;
       }
-      lastLiveName = name;
       rememberDocument(name);
       if (follow) {
-        const hit = matchItem(name);
-        live.matched = Boolean(hit);
-        if (hit) {
-          live.currentScore = hit.score;
-          if (hit.item.id !== live.currentItemId) startItem(hit.item.id);
+        try {
+          const hit = matchItem(name, hintFrom(view));
+          live.matched = Boolean(hit);
+          if (hit) {
+            live.currentScore = hit.score;
+            if (hit.item.id !== live.currentItemId) startItem(hit.item.id, name, hit);
+          } else {
+            // Said in the log, because on the wall it looks like the plan
+            // stopped following: the highlight stays where it was.
+            const staying = state.items.find((it) => it.id === live.currentItemId);
+            log(`live document "${name}" is not in the plan — ${staying ? `"${staying.title}" stays current` : 'no current item'}`);
+          }
+          lastMatchError = '';
+        } catch (err) {
+          // Never silent: a matcher that throws would otherwise leave the
+          // highlight stuck with nothing in the log to say why.
+          const msg = err?.message || String(err);
+          if (msg !== lastMatchError) {
+            lastMatchError = msg;
+            log(`matching "${name}" failed: ${msg}`);
+          }
         }
       }
+      lastLiveName = name;
       // The same document is also a possible service start / end cue.
       syncServiceSafe(Date.now(), name);
       broadcast();
       broadcastTimers();
     }
 
-    function startItem(itemId) {
+    /** Make an item current; `liveName` and `hit` say what placed it, for the log. */
+    function startItem(itemId, liveName, hit) {
       const live = state.live;
       const now = Date.now();
       if (live.currentItemId && live.history[live.currentItemId] && !live.history[live.currentItemId].endedAt) {
@@ -1120,12 +1149,18 @@ module.exports = {
       live.currentItemId = itemId;
       live.history[itemId] = { startedAt: now, endedAt: 0 };
       const item = state.items.find((it) => it.id === itemId);
-      log(`live item → ${item?.title || itemId}`);
+      const how = hit
+        ? ` (${hit.via}${hit.via === 'name' ? ` ${Number(hit.score).toFixed(2)}` : ''}${liveName ? `: "${liveName}"` : ''})`
+        : '';
+      log(`live item → ${item?.title || itemId}${how}`);
     }
 
     function nowNextUnavailable(reason, retryMs) {
       const live = state.live;
       if (live.available || live.reason !== reason) {
+        // Every drop is in the log: a highlight that stopped moving is
+        // otherwise indistinguishable from a feed that went away.
+        log(`ProPresenter module feed unavailable — ${reason}`);
         live.available = false;
         live.reason = reason;
         live.ppReachable = false;

modules/propresenter-timers/client.js

@@ -239,8 +239,6 @@ export default function create({ root, moduleApi }) {
     : variant.startsWith('timer:') ? `propresenter:${variant.slice('timer:'.length)}`
       : variant.startsWith('solo:') ? variant.slice('solo:'.length)
         : '';
-  /** Last label seen for a solo timer, so its card stays labeled if the timer is later deleted upstream. */
-  let lastSoloLabel = '';
 
   /* ── DOM skeleton ───────────────────────────────────────────────── */
 
@@ -376,22 +374,21 @@ export default function create({ root, moduleApi }) {
 
   /* ── state → what this tile shows ───────────────────────────────── */
 
-  /** [{ id, source, items: [{ key, source, timer } | { key, missing }] }] */
+  /** [{ id, source, items: [{ key, source, timer }] }] */
   function visibleGroups() {
     if (!state) return [];
     if (solo) {
       for (const source of state.sources) {
         for (const timer of source.timers) {
           if (keyOf(source, timer) !== solo) continue;
-          lastSoloLabel = timer.label;
           return [{ id: source.id, source, items: [{ key: solo, source, timer }] }];
         }
       }
-      // The timer this tile was added for isn't offered (yet, or any more) —
-      // keep a clearly-labeled card up rather than erroring.
-      const sourceId = solo.slice(0, solo.indexOf(':'));
-      const source = state.sources.find((s) => s.id === sourceId) || null;
-      return [{ id: 'missing', source, items: [{ key: solo, missing: true, source }] }];
+      // The timer this tile was added for is not offered right now. Nothing is
+      // drawn for it — no placeholder that reads like a timer, and never the
+      // full list in its place. The shell folds the tile away on its next
+      // registry refresh (module guide, Presenting multiple tiles).
+      return [];
     }
     const groups = [];
     for (const source of state.sources) {
@@ -451,7 +448,7 @@ export default function create({ root, moduleApi }) {
   /** The parts of a card that only change with the snapshot (label, kind). */
   function updateCard(card, item) {
     card.item = item;
-    card.isClock = !item.missing && item.source?.kind === 'clock';
+    card.isClock = item.source?.kind === 'clock';
     const isLtc = item.source?.kind === 'ltc';
     const badge = card.nameEl.querySelector('.tm-ltc-badge');
     if (isLtc && !badge) {
@@ -462,29 +459,13 @@ export default function create({ root, moduleApi }) {
     } else if (!isLtc && badge) {
       badge.remove();
     }
-    const label = item.missing ? (lastSoloLabel || 'Timer') : card.isClock ? '' : item.timer.label;
+    const label = card.isClock ? '' : item.timer.label;
     if (card.labelEl.textContent !== label) {
       setText(card.labelEl, label);
       needFit = true; // the title's size follows its length
     }
   }
 
-  function updateMissingCard(card) {
-    const source = card.item.source;
-    setText(card.timeEl, '—');
-    card.chars = 5;
-    let note;
-    if (!source) note = 'Source not available — check Admin';
-    else if (source.status === 'ok') note = `Not offered by ${source.label}`;
-    else note = '—';
-    setText(card.statusEl, note);
-    card.statusEl.hidden = false;
-    card.statusEl.className = 'tm-status is-note';
-    card.statusEl.dataset.tone = source && source.status === 'ok' ? 'warn' : 'muted';
-    card.detailEl.hidden = true;
-    setCardClass(card, 'tm-card is-muted is-missing');
-  }
-
   /* ── clocks ─────────────────────────────────────────────────────── */
 
   function clockOptions() {
@@ -633,10 +614,6 @@ export default function create({ root, moduleApi }) {
     let charsChanged = false;
     for (const card of cards.values()) {
       const { item } = card;
-      if (item.missing) {
-        updateMissingCard(card);
-        continue;
-      }
       const { source, timer } = item;
       let text;
       let tone;
@@ -735,8 +712,9 @@ export default function create({ root, moduleApi }) {
       moduleApi.setStatus('connecting', say(waiting));
       return;
     }
-    const n = groups.reduce((a, g) => a + g.items.filter((i) => !i.missing).length, 0);
-    moduleApi.setStatus('ok', `${n} timer${n === 1 ? '' : 's'} from ${shown.length} source${shown.length === 1 ? '' : 's'}`);
+    const n = groups.reduce((a, g) => a + g.items.length, 0);
+    if (solo && n === 0) moduleApi.setStatus('connecting', 'Not offered right now');
+    else moduleApi.setStatus('ok', `${n} timer${n === 1 ? '' : 's'} from ${shown.length} source${shown.length === 1 ? '' : 's'}`);
   }
 
   /* ── main render: diff groups and cards, update in place ────────── */
@@ -791,7 +769,7 @@ export default function create({ root, moduleApi }) {
     let hint = '';
     const groups = visibleGroups();
     if (state && !state.sources.length) hint = 'Every source is switched off — turn one on in Admin.';
-    else if (state && !groups.length) hint = 'Nothing selected — switch a source on in this tile’s settings, or pick timers in the title bar’s timers menu.';
+    else if (state && !groups.length && !solo) hint = 'Nothing selected — switch a source on in this tile’s settings, or pick timers in the title bar’s timers menu.';
     hintEl.hidden = !hint;
     hintEl.textContent = hint;
     groupsEl.hidden = Boolean(hint);

modules/propresenter-timers/module.json

@@ -1,7 +1,7 @@
 {
   "id": "propresenter-timers",
   "name": "Timers",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "proddash": ">=1.4.0",
   "description": "Timers, Clocks, and LTC From configured Modules",
   "provides": [

modules/propresenter-timers/style.css

@@ -295,7 +295,6 @@
 }
 
 /* A solo tile whose timer is no longer offered. */
-[data-module="propresenter-timers"] .tm-card.is-missing { border-style: dashed; }
 
 /* ── the LTC card: visually its own thing ── */
 

modules/spl-meter/client.js

@@ -0,0 +1,610 @@
+/**
+ * SPL Meter tiles.
+ *
+ * Four kinds, all fed by one SSE stream from the module's server:
+ *
+ *   readout      the number, big
+ *   bars         one level bar per channel, with peak hold
+ *   rta          spectrum now, folded to the banding this tile wants
+ *   spectrogram  the same bands over time, either axis
+ *
+ * Nothing here measures anything. The capture child already sent every
+ * averaging and the finest banding, and each tile folds that down to the
+ * view it was configured for. That is the whole design: two dashboards can
+ * watch one room through different settings without either disturbing the
+ * measurement or the other dashboard.
+ */
+
+const FLOOR = -200;
+
+/**
+ * A dead input reads as a number, and a number on a wall is believed. Every
+ * tile therefore refuses to draw a level while the server says the input is
+ * digitally silent, and says why instead.
+ */
+function silentFor(payload) {
+  return payload && payload.silentSec ? payload.silentSec : 0;
+}
+
+function silentText(sec) {
+  if (sec < 90) return `No audio — ${sec} s`;
+  const m = Math.round(sec / 60);
+  return m < 90 ? `No audio — ${m} min` : `No audio — ${(m / 60).toFixed(1)} hours`;
+}
+
+/** Retention per frame for the RTA's smoothing setting. */
+const SMOOTHING = { off: 0, light: 0.45, medium: 0.72, heavy: 0.9 };
+
+export default function create({ root, moduleApi }) {
+  const variant = moduleApi.variant || 'readout';
+  let stream = null;
+  let latest = null;
+  let raf = 0;
+
+  root.classList.add('spl');
+  root.dataset.variant = variant;
+
+  const view = buildView(variant, root, moduleApi);
+
+  function onState(payload) {
+    latest = payload;
+    if (payload.error) {
+      moduleApi.setStatus('error', payload.error);
+    } else if (!payload.frame) {
+      moduleApi.setStatus('connecting', 'waiting for the first reading');
+    } else if (silentFor(payload)) {
+      moduleApi.setStatus('error',
+        `No audio on the chosen input — digital silence for ${silentText(silentFor(payload)).replace('No audio — ', '')}`);
+    } else if (!payload.calibrated) {
+      moduleApi.setStatus('ok', 'Measuring, but uncalibrated — these are dBFS, not dB SPL');
+    } else {
+      moduleApi.setStatus('ok', '');
+    }
+    // Frames land 20×/s; paint on a frame the browser was going to draw
+    // anyway rather than fighting it for every one.
+    if (!raf) raf = requestAnimationFrame(() => { raf = 0; view.render(latest); });
+  }
+
+  return {
+    start() {
+      moduleApi.setStatus('connecting', 'connecting');
+      moduleApi.fetch('/state')
+        .then((r) => r.json())
+        .then(onState)
+        .catch(() => { /* the stream will bring it */ });
+      // Named events go under `events` — a top-level `state(ev)` is silently
+      // never registered, and the tile just sits on whatever /state gave it.
+      stream = moduleApi.sse('/stream', {
+        events: {
+          state(ev) {
+            try { onState(JSON.parse(ev.data)); } catch { /* keep the last good frame */ }
+          },
+        },
+        error() { moduleApi.setStatus('connecting', 'reconnecting'); },
+      });
+    },
+    stop() {
+      if (stream) { stream.close(); stream = null; }
+      if (raf) { cancelAnimationFrame(raf); raf = 0; }
+      view.destroy();
+    },
+    onResize() { view.resize(); },
+  };
+}
+
+/* ── shared helpers ─────────────────────────────────────────────────── */
+
+function pickChannel(payload, settings) {
+  if (!payload || !payload.frame) return null;
+  const want = Number(settings.channel);
+  return payload.frame.ch.find((c) => c.i === want) || payload.frame.ch[0] || null;
+}
+
+/**
+ * The level this tile asked for: an averaging, or one of the fixed metrics.
+ *
+ * Tiles saved by an earlier version carry metrics that no longer exist —
+ * "spl" became an averaging, "leq" became Inf. A layout on a wall somewhere
+ * must not start reading dashes because a setting was renamed, so those map
+ * forward instead of falling through to undefined.
+ */
+const LEGACY_METRIC = { spl: 'level', leq: 'level' };
+const LEGACY_AVERAGING = { leq: 'inf' };
+
+function readValue(ch, settings) {
+  const raw = settings.metric || 'level';
+  const metric = LEGACY_METRIC[raw] || raw;
+  if (metric !== 'level') {
+    return metric in ch ? ch[metric] : ch.fast;
+  }
+  const avg = LEGACY_AVERAGING[raw] || settings.averaging || 'fast';
+  return avg in ch ? ch[avg] : ch.fast;
+}
+
+function fmt(db) {
+  if (!Number.isFinite(db) || db <= FLOOR) return '––.–';
+  return db.toFixed(1);
+}
+
+function themeColor(el, name, fallback) {
+  const v = getComputedStyle(el).getPropertyValue(name).trim();
+  return v || fallback;
+}
+
+function hzLabel(f) {
+  if (f >= 1000) {
+    const k = f / 1000;
+    return (k >= 10 ? Math.round(k) : Math.round(k * 10) / 10) + 'k';
+  }
+  return String(f >= 100 ? Math.round(f) : Math.round(f * 10) / 10);
+}
+
+/**
+ * Fold the 1/48-octave bands on the wire down to this tile's banding.
+ *
+ * Every banding offered divides 48, so a coarser band is an exact sum of
+ * finer ones in the power domain — no interpolation, no resampling. Groups
+ * are keyed on the 1 kHz band (n = 0), which is what keeps folded centres on
+ * the values an RTA is expected to show.
+ *
+ * @returns {{freq:number[], db:number[]}}
+ */
+function foldBands(bands, bandN0, perOctave, denom) {
+  const g = Math.max(1, Math.round(perOctave / denom));
+  const power = new Map();
+  for (let i = 0; i < bands.length; i++) {
+    const n = bandN0 + i;
+    const k = Math.round(n / g);
+    const p = 10 ** (bands[i] / 10);
+    power.set(k, (power.get(k) || 0) + p);
+  }
+  const keys = [...power.keys()].sort((a, b) => a - b);
+  return {
+    freq: keys.map((k) => 1000 * 2 ** ((k * g) / perOctave)),
+    db: keys.map((k) => 10 * Math.log10(Math.max(power.get(k), 1e-20))),
+  };
+}
+
+/**
+ * Which frequency labels fit, most important first.
+ *
+ * Decades earn their place before octaves, octaves before thirds, and
+ * anything that would collide with a label already placed is dropped. That
+ * is what makes the axis thin out as a tile shrinks instead of turning into
+ * a smear.
+ */
+const LABEL_TIERS = [
+  [100, 1000, 10000],
+  [31.5, 63, 250, 500, 2000, 4000, 8000, 20000],
+  [20, 40, 50, 80, 125, 160, 200, 315, 400, 630, 800, 1250, 1600, 2500, 3150, 5000, 6300, 12500, 16000],
+];
+
+function chooseLabels(freqs, positionOf, extent, minGapPx) {
+  const placed = [];
+  for (const tier of LABEL_TIERS) {
+    for (const f of tier) {
+      if (f < freqs[0] * 0.92 || f > freqs[freqs.length - 1] * 1.08) continue;
+      const pos = positionOf(f);
+      if (pos < 0 || pos > extent) continue;
+      if (placed.some((p) => Math.abs(p.pos - pos) < minGapPx)) continue;
+      placed.push({ f, pos });
+    }
+  }
+  return placed.sort((a, b) => a.pos - b.pos);
+}
+
+/* ── views ──────────────────────────────────────────────────────────── */
+
+function buildView(variant, root, moduleApi) {
+  switch (variant) {
+    case 'bars': return barsView(root, moduleApi);
+    case 'rta': return spectrumView(root, moduleApi, false);
+    case 'spectrogram': return spectrumView(root, moduleApi, true);
+    default: return readoutView(root, moduleApi);
+  }
+}
+
+function readoutView(root, moduleApi) {
+  root.innerHTML = `
+    <div class="spl-readout">
+      <div class="spl-value"><span class="spl-num">––.–</span><span class="spl-unit">dB</span></div>
+      <div class="spl-sub"></div>
+    </div>`;
+  const num = root.querySelector('.spl-num');
+  const unit = root.querySelector('.spl-unit');
+  const sub = root.querySelector('.spl-sub');
+  const box = root.querySelector('.spl-readout');
+  const value = root.querySelector('.spl-value');
+  let fitKey = '';
+
+  /**
+   * Grow the number until it fills the tile, measuring the text we actually
+   * have rather than assuming a digit count.
+   *
+   * The CSS can only guess at width — it has to pick a cqw coefficient for
+   * some number of characters, and then "-100.5" overflows the tile that
+   * "-45.9" merely filled. Measuring costs one layout read, and only when
+   * the tile size or the length of the reading changes.
+   */
+  function fit() {
+    const w = root.clientWidth, h = root.clientHeight;
+    const key = `${w}x${h}:${num.textContent.length}:${unit.textContent}:${sub.hidden}`;
+    if (key === fitKey || w < 2 || h < 2) return;
+    fitKey = key;
+
+    const TRIAL = 100;
+    num.style.fontSize = `${TRIAL}px`;
+    unit.style.fontSize = `${TRIAL * 0.26}px`;
+    const natural = value.scrollWidth || 1;
+
+    // Leave the caption its room when it is showing, and a little air either
+    // way so descenders and the tile's padding never clip.
+    const subH = sub.offsetParent ? sub.getBoundingClientRect().height + 6 : 0;
+    const byHeight = (h - subH) * 0.92;
+    const byWidth = ((w - 8) * TRIAL) / natural;
+    const size = Math.max(12, Math.min(byHeight, byWidth));
+    num.style.fontSize = `${size}px`;
+    unit.style.fontSize = `${size * 0.26}px`;
+  }
+
+  return {
+    render(payload) {
+      const s = moduleApi.instanceSettings;
+      const ch = pickChannel(payload, s);
+      const quiet = silentFor(payload);
+      if (quiet && ch) {
+        num.textContent = '––.–';
+        unit.textContent = '';
+        sub.hidden = false;
+        sub.textContent = silentText(quiet);
+        box.dataset.level = 'dead';
+        fit();
+        return;
+      }
+      if (!payload || payload.error || !ch) {
+        num.textContent = '––.–';
+        sub.textContent = payload && payload.error ? payload.error : '';
+        box.dataset.level = 'idle';
+        fit();
+        return;
+      }
+      const value = readValue(ch, s);
+      num.textContent = fmt(value);
+      unit.textContent = payload.calibrated ? 'dB' : 'dBFS';
+
+      const warn = Number(s.warnAt), alarm = Number(s.alarmAt);
+      box.dataset.level = !payload.calibrated ? 'idle'
+        : value >= alarm ? 'alarm' : value >= warn ? 'warn' : 'ok';
+
+      const raw = s.metric || 'level';
+      const metric = LEGACY_METRIC[raw] || raw;
+      const avg = LEGACY_AVERAGING[raw] || s.averaging || 'fast';
+      const label = metric === 'level'
+        ? ({ fast: 'Fast', slow: 'Slow', inf: 'Inf', none: 'No avg' }[avg] || 'Fast')
+        : ({ leq1m: 'Leq 1 min', leq10m: 'Leq 10 min', peakC: 'Peak C' }[metric] || metric);
+      const parts = [`${payload.weighting || '?'} · ${label}`, `ch ${ch.i}`];
+      if (ch.clip) parts.push('CLIP');
+      if (!payload.calibrated) parts.push('uncalibrated');
+      sub.hidden = s.caption === false;
+      sub.textContent = parts.join('  ·  ');
+      fit();
+    },
+    resize() { fitKey = ''; fit(); },
+    destroy() { root.innerHTML = ''; },
+  };
+}
+
+function barsView(root, moduleApi) {
+  root.innerHTML = '<div class="spl-bars"></div>';
+  const host = root.querySelector('.spl-bars');
+  let built = '';
+
+  return {
+    render(payload) {
+      if (!payload || !payload.frame) { host.textContent = payload?.error || ''; built = ''; return; }
+      const chans = payload.frame.ch;
+      const key = chans.map((c) => c.i).join(',');
+      if (key !== built) {
+        built = key;
+        host.innerHTML = chans.map((c) => `
+          <div class="spl-bar" data-ch="${c.i}">
+            <div class="spl-bar-label">${c.i}</div>
+            <div class="spl-bar-track"><div class="spl-bar-fill"></div><div class="spl-bar-peak"></div></div>
+            <div class="spl-bar-value">––.–</div>
+          </div>`).join('');
+      }
+      const s = moduleApi.instanceSettings;
+      const quiet = silentFor(payload);
+      const warn = Number(s.warnAt), alarm = Number(s.alarmAt);
+      const showPeak = s.peakHold !== false;
+      const lo = payload.calibrated ? 40 : -80;
+      const hi = payload.calibrated ? 110 : 0;
+      for (const c of chans) {
+        const el = host.querySelector(`.spl-bar[data-ch="${c.i}"]`);
+        if (!el) continue;
+        const value = readValue(c, { averaging: s.averaging });
+        const pct = (v) => Math.max(0, Math.min(100, ((v - lo) / (hi - lo)) * 100));
+        el.querySelector('.spl-bar-fill').style.width = quiet ? '0%' : `${pct(value)}%`;
+        const peak = el.querySelector('.spl-bar-peak');
+        peak.style.display = showPeak ? '' : 'none';
+        if (showPeak) peak.style.left = `${pct(c.peakC)}%`;
+        el.querySelector('.spl-bar-value').textContent = quiet ? '––.–' : fmt(value);
+        el.dataset.level = quiet ? 'dead' : !payload.calibrated ? 'idle'
+          : value >= alarm ? 'alarm' : value >= warn ? 'warn' : 'ok';
+        el.classList.toggle('clip', !!c.clip);
+      }
+    },
+    resize() {},
+    destroy() { root.innerHTML = ''; },
+  };
+}
+
+/**
+ * RTA bars, or the same folded bands scrolling as a spectrogram.
+ *
+ * Canvas for both, because both redraw wholesale many times a second and a
+ * few hundred animating DOM nodes is how a dashboard starts dropping frames
+ * on the machine that is also running the service.
+ */
+function spectrumView(root, moduleApi, scrolling) {
+  root.innerHTML = '<canvas class="spl-canvas"></canvas>';
+  const canvas = root.querySelector('.spl-canvas');
+  const ctx = canvas.getContext('2d', { alpha: false });
+  /**
+   * The spectrogram's scrolling history, on its own surface.
+   *
+   * It used to scroll by copying the visible canvas onto itself, which also
+   * copied whatever had been drawn on top of it — so every frame dragged the
+   * frequency labels and gridlines one step further along and left a smear.
+   * Only measured pixels belong on a surface that scrolls; annotations are
+   * drawn fresh over the top of it, every frame, and never into it.
+   */
+  let history = null;
+  let historyCtx = null;
+  let painted = false;          // spectrogram: has the history been cleared yet
+  let smoothed = null;          // RTA: displayed values, damped toward the real ones
+  let smoothedFor = '';
+  let axisBtn = null;
+  let axisOverride = null;      // set by the title-bar toggle, which never remounts us
+
+  function axis() {
+    return axisOverride || moduleApi.instanceSettings.axis || 'x';
+  }
+
+  if (scrolling) {
+    // The axis lives here and nowhere else (rule 11): a tile does not offer
+    // the same action twice. Icon only, tooltip carries the words (rule 9).
+    // saveInstanceSettings deliberately does not remount us, so the new
+    // value is held here as well and read back by axis().
+    const swapIcon = '<svg viewBox="0 0 16 16" width="13" height="13" fill="none" '
+      + 'stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">'
+      + '<path d="M2 5h9M8.5 2 11.5 5 8.5 8"/><path d="M14 11H5M7.5 8 4.5 11 7.5 14"/></svg>';
+    const describe = () => (axis() === 'x' ? 'Time left to right' : 'Time top to bottom');
+    axisBtn = moduleApi.header.addButton({
+      icon: swapIcon,
+      title: describe(),
+      onClick() {
+        axisOverride = axis() === 'x' ? 'y' : 'x';
+        moduleApi.saveInstanceSettings({ axis: axisOverride });
+        painted = false;         // the picture means nothing in the other orientation
+        axisBtn.title = describe();
+      },
+    });
+  }
+
+  function sizeCanvas() {
+    const dpr = window.devicePixelRatio || 1;
+    const w = Math.max(1, Math.floor(root.clientWidth));
+    const h = Math.max(1, Math.floor(root.clientHeight));
+    if (canvas.width === Math.floor(w * dpr) && canvas.height === Math.floor(h * dpr)) return false;
+    canvas.width = Math.floor(w * dpr);
+    canvas.height = Math.floor(h * dpr);
+    canvas.style.width = `${w}px`;
+    canvas.style.height = `${h}px`;
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    painted = false;
+    return true;
+  }
+  sizeCanvas();
+
+  function norm(db, calibrated) {
+    const lo = calibrated ? 30 : -100;
+    const hi = calibrated ? 110 : -10;
+    return Math.max(0, Math.min(1, (db - lo) / (hi - lo)));
+  }
+
+  function heat(v) {
+    const stops = [[10, 12, 20], [30, 90, 150], [90, 180, 140], [230, 190, 80], [220, 80, 60]];
+    const x = Math.max(0, Math.min(0.999, v)) * (stops.length - 1);
+    const i = Math.floor(x), t = x - i;
+    const a = stops[i], b = stops[i + 1] || stops[i];
+    return `rgb(${Math.round(a[0] + (b[0] - a[0]) * t)},${Math.round(a[1] + (b[1] - a[1]) * t)},${Math.round(a[2] + (b[2] - a[2]) * t)})`;
+  }
+
+  return {
+    render(payload) {
+      sizeCanvas();
+      const w = canvas.clientWidth, h = canvas.clientHeight;
+      const bg = themeColor(root, '--panel', '#141414');
+      const muted = themeColor(root, '--muted', '#888');
+      const border = themeColor(root, '--border', '#333');
+
+      const quiet = silentFor(payload);
+      if (quiet || !payload || !payload.frame || !payload.frame.bands) {
+        ctx.fillStyle = bg; ctx.fillRect(0, 0, w, h);
+        ctx.fillStyle = muted; ctx.font = '12px system-ui'; ctx.textAlign = 'center';
+        ctx.fillText(quiet ? silentText(quiet)
+                     : (payload?.error || 'Spectrum analysis is off'), w / 2, h / 2);
+        painted = false;
+        return;
+      }
+
+      const s = moduleApi.instanceSettings;
+      const want = Number(s.channel);
+      const idx = Math.max(0, payload.frame.ch.findIndex((c) => c.i === want));
+      const raw = payload.frame.bands[idx] || payload.frame.bands[0] || [];
+      if (!raw.length) return;
+
+      const denom = Number(s.banding) || 3;
+      const folded = foldBands(raw, payload.bandN0 || 0, payload.bandsPerOctave || 48, denom);
+      const freqs = folded.freq;
+      let values = folded.db;
+      const grid = s.gridlines === true;
+      const showLabels = s.labels !== false;
+      const axisPad = showLabels || grid ? 13 : 0;
+
+      if (!scrolling) {
+        // Damp the bars toward the measurement. Cosmetic: `values` is what
+        // gets drawn, never what gets reported.
+        const keep = SMOOTHING[s.smoothing] ?? SMOOTHING.medium;
+        const key = `${denom}:${values.length}`;
+        if (smoothedFor !== key || !smoothed || smoothed.length !== values.length) {
+          smoothed = values.slice();
+          smoothedFor = key;
+        } else if (keep > 0) {
+          for (let i = 0; i < values.length; i++) {
+            smoothed[i] = smoothed[i] * keep + values[i] * (1 - keep);
+          }
+        } else {
+          smoothed = values.slice();
+        }
+        values = smoothed;
+
+        ctx.fillStyle = bg; ctx.fillRect(0, 0, w, h);
+        const plotH = h - axisPad;
+        const bw = w / values.length;
+
+        const xOf = (f) => (Math.log2(f / freqs[0]) / Math.log2(freqs[freqs.length - 1] / freqs[0])) * w;
+        const labels = chooseLabels(freqs, xOf, w, 34);
+
+        if (grid) {
+          ctx.strokeStyle = border; ctx.lineWidth = 1; ctx.globalAlpha = 0.5;
+          ctx.beginPath();
+          for (const l of labels) {
+            const x = Math.round(l.pos) + 0.5;
+            ctx.moveTo(x, 0); ctx.lineTo(x, plotH);
+          }
+          for (let g = 0.2; g < 1; g += 0.2) {
+            const y = Math.round(plotH * g) + 0.5;
+            ctx.moveTo(0, y); ctx.lineTo(w, y);
+          }
+          ctx.stroke(); ctx.globalAlpha = 1;
+        }
+
+        for (let i = 0; i < values.length; i++) {
+          const v = norm(values[i], payload.calibrated);
+          const bh = v * plotH;
+          ctx.fillStyle = heat(v);
+          ctx.fillRect(i * bw, plotH - bh, Math.max(1, bw - (bw > 3 ? 1 : 0)), bh);
+        }
+
+        if (showLabels) {
+          ctx.fillStyle = muted; ctx.font = '9px system-ui'; ctx.textAlign = 'center';
+          for (const l of labels) ctx.fillText(hzLabel(l.f), l.pos, h - 3);
+        }
+        return;
+      }
+
+      // ── spectrogram ──
+      const timeX = axis() === 'x';
+      const colW = 2;
+      // A label along the bottom needs only its line height; one down the
+      // side has to fit "12.5k" beside the plot rather than on top of it.
+      const gutter = (showLabels || grid) ? (timeX ? 30 : axisPad) : 0;
+      // Labels belong beside the frequency axis: down the left when frequency
+      // runs vertically, along the bottom when it runs horizontally.
+      const plotX = timeX ? gutter : 0;
+      const plotW = timeX ? w - gutter : w;
+      const plotH = timeX ? h : h - gutter;
+      const freqExtent = timeX ? plotH : plotW;
+      const timeExtent = timeX ? plotW : plotH;
+      if (plotW < 4 || plotH < 4) return;
+
+      // The history surface is sized to the plot, in device pixels, and is
+      // thrown away whenever that geometry changes — a scroll buffer means
+      // nothing once it is being stretched into a different shape.
+      const dpr = window.devicePixelRatio || 1;
+      const needW = Math.max(1, Math.round(plotW * dpr));
+      const needH = Math.max(1, Math.round(plotH * dpr));
+      if (!history || history.width !== needW || history.height !== needH) {
+        history = document.createElement('canvas');
+        history.width = needW;
+        history.height = needH;
+        historyCtx = history.getContext('2d', { alpha: false });
+        historyCtx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        painted = false;
+      }
+      if (!painted) {
+        historyCtx.fillStyle = bg;
+        historyCtx.fillRect(0, 0, plotW, plotH);
+        painted = true;
+      }
+
+      // Scroll the history, then add the newest column. The source rectangle
+      // is in device pixels and the destination in CSS pixels, because the
+      // context carries the dpr transform but the canvas as an image source
+      // does not.
+      historyCtx.drawImage(history, 0, 0, history.width, history.height,
+                           timeX ? -colW : 0, timeX ? 0 : -colW, plotW, plotH);
+
+      const bandExtent = freqExtent / values.length;
+      for (let i = 0; i < values.length; i++) {
+        historyCtx.fillStyle = heat(norm(values[i], payload.calibrated));
+        if (timeX) {
+          // Low frequencies at the bottom, as every spectrogram has them.
+          historyCtx.fillRect(timeExtent - colW, freqExtent - (i + 1) * bandExtent,
+                              colW, Math.ceil(bandExtent) + 1);
+        } else {
+          // Low frequencies at the left.
+          historyCtx.fillRect(i * bandExtent, timeExtent - colW,
+                              Math.ceil(bandExtent) + 1, colW);
+        }
+      }
+
+      // Repaint the visible canvas from scratch every frame: history first,
+      // annotations over it. Nothing drawn here can ever reach the scroll.
+      ctx.fillStyle = bg; ctx.fillRect(0, 0, w, h);
+      ctx.drawImage(history, 0, 0, history.width, history.height,
+                    plotX, 0, plotW, plotH);
+
+      if (!grid && !showLabels) return;
+
+      const span = Math.log2(freqs[freqs.length - 1] / freqs[0]);
+      const posOf = (f) => {
+        const t = Math.log2(f / freqs[0]) / span;
+        return timeX ? plotH - t * plotH : plotX + t * plotW;
+      };
+      const labels = chooseLabels(freqs, posOf, timeX ? plotH : w, timeX ? 14 : 34);
+
+      if (grid) {
+        ctx.strokeStyle = border; ctx.lineWidth = 1; ctx.globalAlpha = 0.35;
+        ctx.beginPath();
+        for (const l of labels) {
+          if (timeX) {
+            const y = Math.round(l.pos) + 0.5;
+            ctx.moveTo(plotX, y); ctx.lineTo(w, y);
+          } else {
+            const x = Math.round(l.pos) + 0.5;
+            ctx.moveTo(x, 0); ctx.lineTo(x, plotH);
+          }
+        }
+        ctx.stroke(); ctx.globalAlpha = 1;
+      }
+
+      if (showLabels) {
+        ctx.fillStyle = muted; ctx.font = '9px system-ui';
+        ctx.textAlign = timeX ? 'right' : 'center';
+        for (const l of labels) {
+          if (timeX) {
+            ctx.fillText(hzLabel(l.f), gutter - 2,
+                         Math.max(7, Math.min(h - 2, l.pos + 3)));
+          } else {
+            ctx.fillText(hzLabel(l.f), l.pos, h - 3);
+          }
+        }
+      }
+    },
+    resize() { sizeCanvas(); },
+    destroy() { root.innerHTML = ''; },
+  };
+}

modules/spl-meter/module.json

@@ -0,0 +1,94 @@
+{
+  "id": "spl-meter",
+  "name": "SPL Meter",
+  "version": "0.4.1",
+  "proddash": ">=1.5.0",
+  "description": "Calibrated sound level, Leq and RTA from an audio input on this machine",
+  "permissions": [
+    {
+      "kind": "microphone",
+      "reason": "Measuring sound level from an audio input on this machine"
+    }
+  ],
+  "client": "client.js",
+  "server": "server.js",
+  "style": "style.css",
+  "minSize": {
+    "w": 2,
+    "h": 1
+  },
+  "defaultSize": {
+    "w": 3,
+    "h": 2
+  },
+  "configGroups": {
+    "Input": {
+      "toggle": "enabled"
+    },
+    "Measurement": {
+      "columns": 2
+    },
+    "Calibration": {
+      "collapsed": "whenSet",
+      "help": "A sound level calibrator fits over the microphone capsule and emits a known level, almost always 94 dB at 1 kHz. Put it on, press Measure beside the channel, and copy the offset it reports into the box. Without this the meter still works, but it reads in dB relative to full scale and every tile says so."
+    }
+  },
+  "configSchema": {
+    "enabled": {
+      "type": "switch",
+      "label": "Sound level measurement",
+      "group": "Input",
+      "default": false
+    },
+    "device": {
+      "type": "select",
+      "label": "Audio device",
+      "group": "Input",
+      "showWhen": "enabled",
+      "default": "",
+      "optionsRoute": "/devices"
+    },
+    "channels": {
+      "type": "string",
+      "label": "Channels on that device (1-based, comma separated)",
+      "group": "Input",
+      "showWhen": "enabled",
+      "default": "1",
+      "help": "One meter per channel — \"1\" for a single measurement mic, \"1,2\" for a stereo pair."
+    },
+    "weighting": {
+      "type": "select",
+      "label": "Weighting",
+      "group": "Measurement",
+      "default": "A",
+      "options": [
+        {
+          "value": "A",
+          "label": "A — how loud it sounds"
+        },
+        {
+          "value": "C",
+          "label": "C — keeps the low end"
+        },
+        {
+          "value": "Z",
+          "label": "Z — no weighting at all"
+        }
+      ]
+    },
+    "bands": {
+      "type": "switch",
+      "label": "Spectrum analysis",
+      "group": "Measurement",
+      "default": true,
+      "help": "1/48-octave bands for the RTA and spectrogram tiles, which each fold them to their own banding. Turn it off if you only ever show the number."
+    },
+    "calibration": {
+      "type": "string",
+      "label": "Offsets in dB, one per channel",
+      "group": "Calibration",
+      "default": "",
+      "help": "Leave empty and every reading is dB relative to full scale, labelled dBFS so nobody mistakes it for real SPL."
+    }
+  }
+}

modules/spl-meter/server.js

@@ -0,0 +1,448 @@
+'use strict';
+
+/**
+ * SPL Meter server entry.
+ *
+ * Owns one capture child (spl-listener.js) and fans its frames out to every
+ * tile over SSE. Browsers never see the audio device, only the numbers.
+ *
+ *   GET  /stream      → SSE, `state` events at the capture rate
+ *   GET  /state       → the latest frame, for an instant first paint
+ *   GET  /devices     → input devices, for the admin page's picker
+ *   GET  /channels    → configured channels, for the tile gear picker
+ *   POST /reset       → clear Leq and peak hold
+ *   GET  /measure     → what a calibrator is reading right now, so the
+ *                       admin page can tell the operator what to type
+ *
+ * Frames arrive 20×/s. That is the right rate for a meter to feel live and
+ * the wrong rate to re-broadcast blindly, so the SSE fan-out drops a frame
+ * whose numbers round to what the last one said.
+ */
+
+const path = require('path');
+const { createSplListener } = require('./spl-listener');
+
+/** Reference level of a sound level calibrator. Effectively always 94 dB. */
+const CALIBRATOR_DB = 94;
+/** How long /measure averages for. Long enough to ride out a wobble, short
+    enough that nobody standing at the microphone gets bored. */
+const MEASURE_MS = 3000;
+/** SSE comment ping — keeps idle connections alive through sleepy Wi-Fi. */
+const PING_MS = 15000;
+
+/**
+ * Below this, unweighted, the input is not quiet — it is not there.
+ *
+ * A real input always carries something: a microphone in a silent room still
+ * reads about -83 dBFS, and even a muted converter dithers around -120. Only
+ * a stream of actual zeros reaches the capture tool's -200 floor, and that
+ * means the device handed us nothing at all.
+ */
+const SILENCE_DBFS = -150;
+/** How long that has to hold before saying so, so a gap between buffers or a
+    device changing sample rate mid-stream doesn't cry wolf. */
+const SILENCE_GRACE_MS = 5000;
+
+/** Set by init(), read by routes() — both are rebuilt together on re-init. */
+let state = null;
+
+/* ── shared tile settings ───────────────────────────────────────────── */
+
+const CHANNEL_FIELD = {
+  type: 'select', label: 'Channel', default: '', optionsRoute: '/channels',
+};
+
+/**
+ * Averaging is a view choice, not a measurement one: the capture child
+ * computes all four every frame and sends all four, so one dashboard on Fast
+ * and another on Inf are reading the same measurement two ways.
+ */
+function averagingField() {
+  return {
+    type: 'select', label: 'Averaging', default: 'fast',
+    options: [
+      { value: 'fast', label: 'Fast · 125 ms' },
+      { value: 'slow', label: 'Slow · 1 s' },
+      { value: 'inf', label: 'Inf · since reset' },
+      { value: 'none', label: 'None' },
+    ],
+  };
+}
+
+/**
+ * Banding folds the 1/48-octave bands on the wire down to something
+ * readable. Coarser is an exact sum of finer, so this costs nothing and
+ * disturbs no other tile.
+ */
+const BANDING_FIELD = {
+  type: 'select', label: 'Banding', default: '3',
+  options: [
+    { value: '3', label: '1/3 octave' },
+    { value: '6', label: '1/6 octave' },
+    { value: '12', label: '1/12 octave' },
+    { value: '24', label: '1/24 octave' },
+    { value: '48', label: '1/48 octave' },
+  ],
+};
+
+function parseChannels(raw) {
+  return String(raw || '1')
+    .split(',')
+    .map((s) => Number(s.trim()))
+    .filter((n) => Number.isInteger(n) && n >= 1 && n <= 64);
+}
+
+function parseCalibration(raw) {
+  if (!String(raw || '').trim()) return [];
+  return String(raw)
+    .split(',')
+    .map((s) => Number(s.trim()))
+    .filter((n) => Number.isFinite(n));
+}
+
+module.exports = {
+  init({ config, log }) {
+    const channels = parseChannels(config.channels);
+    const calibration = parseCalibration(config.calibration);
+    const moduleDir = __dirname;
+
+    state = {
+      channels,
+      calibrated: calibration.length === channels.length && channels.length > 0,
+      frame: null,
+      meta: null,
+      error: '',
+      streams: new Set(),
+      silentSince: null,
+      listener: null,
+      lastSent: '',
+      pinger: null,
+    };
+
+    if (!config.enabled) {
+      state.error = 'Sound level measurement is off — turn it on in ProdDash settings';
+      return { stop() { teardown(); }, health: () => ({ status: 'error', message: state.error }) };
+    }
+    if (!config.device) {
+      state.error = 'No audio device chosen yet';
+      return { stop() { teardown(); }, health: () => ({ status: 'error', message: state.error }) };
+    }
+    if (!channels.length) {
+      state.error = `Cannot read "${config.channels}" as a channel list — try 1, or 1,2`;
+      return { stop() { teardown(); }, health: () => ({ status: 'error', message: state.error }) };
+    }
+    if (calibration.length && calibration.length !== channels.length) {
+      state.error = `${channels.length} channel(s) but ${calibration.length} calibration offset(s) — `
+        + 'give one per channel, or leave the offsets empty';
+      return { stop() { teardown(); }, health: () => ({ status: 'error', message: state.error }) };
+    }
+
+    state.listener = createSplListener({
+      device: config.device,
+      channels,
+      weighting: config.weighting || 'A',
+      bands: config.bands !== false,
+      calibration,
+      moduleDir,
+      log,
+      onUpdate(update) {
+        if (!state) return;        // a frame in flight when the module unmounted
+        if (update.error) {
+          if (update.error !== state.error) log(update.error);
+          state.error = update.error;
+          state.frame = null;
+          broadcast();
+          return;
+        }
+        state.error = '';
+        state.frame = update.frame;
+        state.meta = update.meta;
+        // Digital silence on every channel is a dead input, not a reading.
+        // Saying "ok" through this is what made a stopped Dante device look
+        // like a frozen module for a day and a half.
+        const dead = update.frame.ch.every(
+          (c) => !Number.isFinite(c.dbfs) || c.dbfs <= SILENCE_DBFS);
+        state.silentSince = dead ? (state.silentSince || Date.now()) : null;
+        broadcast();
+      },
+    });
+
+    const mineStreams = state.streams;
+    state.pinger = setInterval(() => {
+      for (const res of mineStreams) {
+        try { res.write(': ping\n\n'); } catch { mineStreams.delete(res); }
+      }
+    }, PING_MS);
+
+    return {
+      stop() { teardown(); },
+      health() {
+        if (state.error) return { status: 'error', message: state.error };
+        if (!state.frame) return { status: 'connecting', message: 'waiting for the first reading' };
+        const quiet = silentMs();
+        if (quiet > SILENCE_GRACE_MS) {
+          return { status: 'error',
+                   message: `No audio from ${config.device} — digital silence for ${describe(quiet)}` };
+        }
+        const n = state.channels.length;
+        const what = `${n} channel${n === 1 ? '' : 's'} on ${config.device}`;
+        return state.calibrated
+          ? { status: 'ok', message: what }
+          : { status: 'ok', message: `${what} — uncalibrated, reading dBFS` };
+      },
+    };
+  },
+
+  /**
+   * Four tile kinds, each with only the settings that do something to it.
+   *
+   * An entry's own instanceSchema replaces the module's, which is the point:
+   * an RTA has no use for an alarm threshold and a readout has no use for a
+   * banding, and offering either is how a gear popover stops being read.
+   *
+   * Every setting here is a view choice. None of them reach the capture
+   * child — it already sends every averaging and the finest banding, so two
+   * dashboards can disagree about how to draw the same room.
+   */
+  tiles() {
+    return [
+      {
+        id: 'readout', name: 'SPL', description: 'The level, big',
+        defaultSize: { w: 2, h: 1 }, minSize: { w: 1, h: 1 },
+        instanceGroups: { Thresholds: { columns: 2 } },
+        instanceSchema: {
+          channel: CHANNEL_FIELD,
+          averaging: averagingField(),
+          metric: {
+            type: 'select', label: 'Show', default: 'level',
+            options: [
+              { value: 'level', label: 'Level' },
+              { value: 'leq1m', label: 'Leq 1 min' },
+              { value: 'leq10m', label: 'Leq 10 min' },
+              { value: 'peakC', label: 'Peak C' },
+            ],
+          },
+          caption: { type: 'switch', label: 'Caption', default: true },
+          warnAt: { type: 'number', label: 'Amber above', group: 'Thresholds', default: 95 },
+          alarmAt: { type: 'number', label: 'Red above', group: 'Thresholds', default: 100 },
+        },
+      },
+      {
+        id: 'bars', name: 'SPL Levels', description: 'One bar per channel, with peak hold',
+        defaultSize: { w: 3, h: 2 }, minSize: { w: 2, h: 1 },
+        instanceGroups: { Thresholds: { columns: 2 } },
+        instanceSchema: {
+          averaging: averagingField(),
+          peakHold: { type: 'switch', label: 'Peak hold', default: true },
+          warnAt: { type: 'number', label: 'Amber above', group: 'Thresholds', default: 95 },
+          alarmAt: { type: 'number', label: 'Red above', group: 'Thresholds', default: 100 },
+        },
+      },
+      {
+        id: 'rta', name: 'RTA', description: 'Spectrum now, at your choice of banding',
+        defaultSize: { w: 5, h: 3 }, minSize: { w: 3, h: 2 },
+        instanceSchema: {
+          channel: CHANNEL_FIELD,
+          averaging: averagingField(),
+          banding: BANDING_FIELD,
+          smoothing: {
+            type: 'select', label: 'Smoothing', default: 'medium',
+            options: [
+              { value: 'off', label: 'Off' },
+              { value: 'light', label: 'Light' },
+              { value: 'medium', label: 'Medium' },
+              { value: 'heavy', label: 'Heavy' },
+            ],
+          },
+          labels: { type: 'switch', label: 'Labels', default: true },
+          gridlines: { type: 'switch', label: 'Gridlines', default: false },
+        },
+      },
+      {
+        id: 'spectrogram', name: 'Spectrogram', description: 'Spectrum over time',
+        defaultSize: { w: 5, h: 3 }, minSize: { w: 3, h: 2 },
+        instanceSchema: {
+          channel: CHANNEL_FIELD,
+          banding: BANDING_FIELD,
+          labels: { type: 'switch', label: 'Labels', default: true },
+          gridlines: { type: 'switch', label: 'Gridlines', default: false },
+        },
+      },
+    ];
+  },
+
+  routes({ config, log }) {
+    return {
+      'GET /state': (req, res) => {
+        json(res, 200, snapshot());
+      },
+
+      'GET /stream': (req, 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');
+        try {
+          res.write(`event: state\ndata: ${JSON.stringify(snapshot())}\n\n`);
+        } catch { return; }
+        // Hold this mount's set, not `state`. teardown() nulls `state` and
+        // then ends every stream, which fires these close handlers — a
+        // handler that reached through `state` threw on null and took the
+        // whole server down with it, on any re-init with a browser
+        // connected. Deleting from a set nobody reads any more is harmless.
+        const streams = state.streams;
+        streams.add(res);
+        req.on('close', () => streams.delete(res));
+      },
+
+      /** Device list for the admin page. Runs the capture tool's --list,
+          which is the only thing that knows what CoreAudio can see. */
+      'GET /devices': async (req, res) => {
+        try {
+          const devices = await listDevices();
+          json(res, 200, {
+            options: devices.map((d) => ({
+              value: d.name,
+              label: `${d.name} — ${d.channels} ch @ ${Math.round(d.sampleRate)} Hz`,
+            })),
+          });
+        } catch (err) {
+          log(`device list failed: ${err.message}`);
+          json(res, 200, { options: [] });   // the saved value stays selectable
+        }
+      },
+
+      /** Channel list for a tile's gear popover. */
+      'GET /channels': (req, res) => {
+        json(res, 200, {
+          options: state.channels.map((c) => ({ value: String(c), label: `Channel ${c}` })),
+        });
+      },
+
+      'POST /reset': (req, res) => {
+        if (state.listener) state.listener.reset();
+        json(res, 200, { ok: true });
+      },
+
+      /**
+       * What the microphone is hearing right now, unweighted and
+       * uncalibrated, plus the offset that would make it read 94 dB.
+       *
+       * The module cannot write its own admin config, so this does not save
+       * anything — it hands back a number for the operator to paste into the
+       * Calibration box. Honest, if one step longer than it should be.
+       */
+      'GET /measure': (req, res) => {
+        if (!state.listener || state.error) {
+          json(res, 409, { error: state.error || 'not measuring' });
+          return;
+        }
+        const wanted = Number(new URLSearchParams(req.search || '').get('channel'))
+          || state.channels[0];
+        const samples = [];
+        const started = Date.now();
+        const tick = setInterval(() => {
+          if (!state) { clearInterval(tick); return; }   // module unmounted mid-measure
+          const ch = state.frame && state.frame.ch.find((c) => c.i === wanted);
+          if (ch && Number.isFinite(ch.dbfs) && ch.dbfs > -200) samples.push(ch.dbfs);
+          if (Date.now() - started < MEASURE_MS) return;
+          clearInterval(tick);
+          if (samples.length < 5) {
+            json(res, 200, {
+              channel: wanted,
+              error: 'No steady tone on that channel — check the calibrator is on and seated',
+            });
+            return;
+          }
+          // Mean of the linear powers, not of the decibels: averaging dB
+          // would quietly under-read a signal that wobbles at all.
+          const power = samples.reduce((s, db) => s + 10 ** (db / 10), 0) / samples.length;
+          const measured = 10 * Math.log10(power);
+          json(res, 200, {
+            channel: wanted,
+            measured: Math.round(measured * 100) / 100,
+            reference: CALIBRATOR_DB,
+            offset: Math.round((CALIBRATOR_DB - measured) * 100) / 100,
+            samples: samples.length,
+          });
+        }, 100);
+        req.on('close', () => clearInterval(tick));
+      },
+    };
+  },
+};
+
+/* ── helpers ────────────────────────────────────────────────────────── */
+
+/** How long every channel has been at digital silence, in ms. */
+function silentMs() {
+  return state && state.silentSince ? Date.now() - state.silentSince : 0;
+}
+
+function describe(ms) {
+  const s = Math.round(ms / 1000);
+  if (s < 90) return `${s} s`;
+  const m = Math.round(s / 60);
+  return m < 90 ? `${m} min` : `${(m / 60).toFixed(1)} hours`;
+}
+
+function snapshot() {
+  if (!state) return { error: 'not measuring', calibrated: false, channels: [], frame: null, silentSec: 0 };
+  // Seconds, not milliseconds: this goes on the wire 20×/s and a value that
+  // changed every frame would make the fan-out's change check useless.
+  const quiet = silentMs();
+  return {
+    error: state.error,
+    silentSec: quiet > SILENCE_GRACE_MS ? Math.round(quiet / 1000) : 0,
+    calibrated: state.calibrated,
+    channels: state.channels,
+    weighting: state.meta ? state.meta.weighting : '',
+    bandCentres: state.meta ? state.meta.bands : [],
+    bandN0: state.meta ? state.meta.bandN0 : 0,
+    bandsPerOctave: state.meta ? state.meta.bandsPerOctave : 48,
+    frame: state.frame,
+  };
+}
+
+function broadcast() {
+  if (!state) return;              // a listener callback landing after teardown
+  const payload = snapshot();
+  const line = JSON.stringify(payload);
+  if (line === state.lastSent) return;      // nothing moved since last frame
+  state.lastSent = line;
+  for (const res of state.streams) {
+    try { res.write(`event: state\ndata: ${line}\n\n`); } catch { state.streams.delete(res); }
+  }
+}
+
+function teardown() {
+  if (!state) return;
+  if (state.listener) state.listener.stop();
+  clearInterval(state.pinger);
+  for (const res of state.streams) { try { res.end(); } catch { /* already gone */ } }
+  state.streams.clear();
+  state = null;
+}
+
+function listDevices() {
+  return new Promise((resolve, reject) => {
+    const { execFile } = require('child_process');
+    execFile(path.join(__dirname, 'spl-capture'), ['--list'], { timeout: 10000 },
+      (err, stdout) => {
+        if (err && !stdout) { reject(err); return; }
+        try { resolve(JSON.parse(stdout).devices || []); }
+        catch (e) { reject(e); }
+      });
+  });
+}
+
+function json(res, code, body) {
+  const text = JSON.stringify(body);
+  res.writeHead(code, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(text),
+  });
+  res.end(text);
+}

modules/spl-meter/spl-capture.swift

@@ -0,0 +1,735 @@
+// spl-capture — calibrated sound-level measurement from a CoreAudio input.
+//
+// Sibling of the Timers module's ltc-capture: same device enumeration, same
+// "stdout is data, stderr is talk" contract, same one-file-no-dependencies
+// rule. The difference is where the work happens. LTC ships raw samples to
+// Node because the decode is cheap and single-channel; sound level is
+// filtering and FFTs over every channel at the device's rate, so the
+// measurement is done here and only the answers cross the pipe.
+//
+// Everything below uses Accelerate, which ships with macOS. No third-party
+// code, no package manager, ~2 s to build:
+//
+//   swiftc -O -o modules/spl-meter/spl-capture \
+//     modules/spl-meter/spl-capture.swift
+//
+//   spl-capture --list
+//       every input-capable device: name, input channels, sample rate
+//   spl-capture --device "Dante Via 16 Channel" --channels 1,2 [--cal 0,0]
+//       measures those 1-based channels and writes one JSON line per frame
+//       to stdout, 20×/s. --cal takes one dB offset per channel, in the same
+//       order, from the calibration route (94 dB reference minus what we
+//       measured). With no --cal the numbers are dBFS-relative and the line
+//       says calibrated:false, so nothing downstream can mistake them for
+//       real SPL.
+//
+// Per channel, per frame: the level at EVERY averaging a dashboard might
+// ask for — fast (125 ms), slow (1 s), inf (Leq since reset) and none (this
+// block alone) — plus rolling 1- and 10-minute Leq, C- and Z-weighted peak,
+// raw dBFS and a clip flag. Optionally a 1/48-octave band set for the RTA
+// and spectrogram tiles, only when --bands is passed.
+//
+// Everything is sent every frame on purpose. Two dashboards watching the
+// same room may want different averaging and different banding, and neither
+// choice may disturb the other or restart capture. So the measurement is
+// made once, at the finest resolution anyone asked for, and each tile folds
+// it down to the view it wants. Nothing here is per-viewer state.
+//
+// Weighting filters are IEC 61672 pole/zero prototypes, bilinear-transformed
+// with the top section prewarped, then normalised to exactly 0 dB at 1 kHz.
+// Verified against the standard's table: within 0.15 dB from 31.5 Hz to
+// 4 kHz. The top octave is where the bilinear transform runs out of room —
+// at 48 kHz the 16 kHz point sits about 3 dB low. That is a rounding error
+// on a broadband programme number (A-weighting has already thrown 6.6 dB
+// away up there) but it is a real limit, and the fix if it ever matters is
+// to run the weighting at 96 kHz. `--selftest` prints the table so this
+// claim can be checked rather than believed.
+//
+// macOS asks for microphone permission on first use, and the prompt belongs
+// to whatever launched this — the ProdDash launcher, or Terminal. A server
+// started over SSH gets SILENT ZEROS from every input with no error at all,
+// which shows up downstream as a meter pinned at the floor.
+
+import AVFoundation
+import Accelerate
+import CoreAudio
+import Foundation
+
+func fail(_ msg: String) -> Never {
+    FileHandle.standardError.write(("spl-capture: " + msg + "\n").data(using: .utf8)!)
+    exit(2)
+}
+
+func note(_ msg: String) {
+    FileHandle.standardError.write(("spl-capture: " + msg + "\n").data(using: .utf8)!)
+}
+
+/* ── CoreAudio device enumeration ───────────────────────────────────── */
+
+struct InputDevice {
+    let id: AudioDeviceID
+    let name: String
+    let uid: String
+    let channels: Int
+    let sampleRate: Double
+}
+
+func stringProperty(_ id: AudioObjectID, _ selector: AudioObjectPropertySelector) -> String {
+    var addr = AudioObjectPropertyAddress(
+        mSelector: selector, mScope: kAudioObjectPropertyScopeGlobal,
+        mElement: kAudioObjectPropertyElementMain)
+    var ref: Unmanaged<CFString>? = nil
+    var size = UInt32(MemoryLayout<Unmanaged<CFString>?>.size)
+    let err = withUnsafeMutablePointer(to: &ref) {
+        AudioObjectGetPropertyData(id, &addr, 0, nil, &size, $0)
+    }
+    guard err == noErr, let value = ref?.takeRetainedValue() else { return "" }
+    return value as String
+}
+
+func sampleRateProperty(_ id: AudioObjectID) -> Double {
+    var addr = AudioObjectPropertyAddress(
+        mSelector: kAudioDevicePropertyNominalSampleRate,
+        mScope: kAudioObjectPropertyScopeGlobal,
+        mElement: kAudioObjectPropertyElementMain)
+    var rate: Float64 = 0
+    var size = UInt32(MemoryLayout<Float64>.size)
+    guard AudioObjectGetPropertyData(id, &addr, 0, nil, &size, &rate) == noErr else { return 0 }
+    return rate
+}
+
+func inputChannelCount(_ id: AudioDeviceID) -> Int {
+    var addr = AudioObjectPropertyAddress(
+        mSelector: kAudioDevicePropertyStreamConfiguration,
+        mScope: kAudioDevicePropertyScopeInput,
+        mElement: kAudioObjectPropertyElementMain)
+    var size: UInt32 = 0
+    guard AudioObjectGetPropertyDataSize(id, &addr, 0, nil, &size) == noErr, size > 0 else { return 0 }
+    let listPtr = UnsafeMutableRawPointer.allocate(
+        byteCount: Int(size), alignment: MemoryLayout<AudioBufferList>.alignment)
+    defer { listPtr.deallocate() }
+    guard AudioObjectGetPropertyData(id, &addr, 0, nil, &size, listPtr) == noErr else { return 0 }
+    let buffers = UnsafeMutableAudioBufferListPointer(
+        listPtr.assumingMemoryBound(to: AudioBufferList.self))
+    return buffers.reduce(0) { $0 + Int($1.mNumberChannels) }
+}
+
+func listInputDevices() -> [InputDevice] {
+    var addr = AudioObjectPropertyAddress(
+        mSelector: kAudioHardwarePropertyDevices,
+        mScope: kAudioObjectPropertyScopeGlobal,
+        mElement: kAudioObjectPropertyElementMain)
+    var size: UInt32 = 0
+    guard AudioObjectGetPropertyDataSize(
+        AudioObjectID(kAudioObjectSystemObject), &addr, 0, nil, &size) == noErr else { return [] }
+    var ids = [AudioDeviceID](repeating: 0, count: Int(size) / MemoryLayout<AudioDeviceID>.size)
+    guard AudioObjectGetPropertyData(
+        AudioObjectID(kAudioObjectSystemObject), &addr, 0, nil, &size, &ids) == noErr else { return [] }
+
+    var out: [InputDevice] = []
+    for id in ids {
+        let channels = inputChannelCount(id)
+        if channels == 0 { continue }
+        out.append(InputDevice(id: id,
+                               name: stringProperty(id, kAudioObjectPropertyName),
+                               uid: stringProperty(id, kAudioDevicePropertyDeviceUID),
+                               channels: channels,
+                               sampleRate: sampleRateProperty(id)))
+    }
+    return out
+}
+
+/* ── frequency weighting (IEC 61672) ────────────────────────────────── */
+
+/// Pole frequencies from the standard.
+private let wf1 = 2 * Double.pi * 20.598997
+private let wf2 = 2 * Double.pi * 107.65265
+private let wf3 = 2 * Double.pi * 737.86223
+private let wf4 = 2 * Double.pi * 12194.217
+
+/// Bilinear-transform one analogue biquad into [b0, b1, b2, a1, a2].
+///
+/// `warpAt` prewarps the transform so that section's critical frequency
+/// lands where the analogue prototype put it. Without it the plain
+/// `c = 2·fs` mapping squeezes the top octave badly — it is worth about
+/// 3 dB at 16 kHz for the 12.2 kHz pole pair.
+func bilinear(_ b: (Double, Double, Double), _ a: (Double, Double, Double),
+              fs: Double, warpAt: Double = 0) -> [Double] {
+    let c = warpAt > 0 ? warpAt / tan(warpAt / (2 * fs)) : 2 * fs
+    let c2 = c * c
+    let B0 = b.0 * c2 + b.1 * c + b.2
+    let B1 = 2 * b.2 - 2 * b.0 * c2
+    let B2 = b.0 * c2 - b.1 * c + b.2
+    let A0 = a.0 * c2 + a.1 * c + a.2
+    let A1 = 2 * a.2 - 2 * a.0 * c2
+    let A2 = a.0 * c2 - a.1 * c + a.2
+    return [B0 / A0, B1 / A0, B2 / A0, A1 / A0, A2 / A0]
+}
+
+/// |H(f)| of a cascade of biquad sections, used to normalise gain at 1 kHz
+/// and to print the verification table.
+func cascadeResponse(_ secs: [Double], _ f: Double, fs: Double) -> Double {
+    let th = 2 * Double.pi * f / fs
+    var reT = 1.0, imT = 0.0
+    for s in stride(from: 0, to: secs.count, by: 5) {
+        let (b0, b1, b2, a1, a2) = (secs[s], secs[s+1], secs[s+2], secs[s+3], secs[s+4])
+        let nr = b0 + b1 * cos(th) + b2 * cos(2 * th)
+        let ni = -(b1 * sin(th) + b2 * sin(2 * th))
+        let dr = 1 + a1 * cos(th) + a2 * cos(2 * th)
+        let di = -(a1 * sin(th) + a2 * sin(2 * th))
+        let dd = dr * dr + di * di
+        guard dd > 0 else { return 0 }
+        let qr = (nr * dr + ni * di) / dd, qi = (ni * dr - nr * di) / dd
+        let t = reT * qr - imT * qi
+        imT = reT * qi + imT * qr
+        reT = t
+    }
+    return (reT * reT + imT * imT).squareRoot()
+}
+
+enum Weighting: String {
+    case a = "A", c = "C", z = "Z"
+
+    /// Biquad sections for this weighting at `fs`, normalised to 0 dB at 1 kHz.
+    func sections(fs: Double) -> [Double] {
+        var s: [Double]
+        switch self {
+        case .a:
+            s = bilinear((1, 0, 0), (1, 2 * wf1, wf1 * wf1), fs: fs)
+              + bilinear((1, 0, 0), (1, wf2 + wf3, wf2 * wf3), fs: fs)
+              + bilinear((0, 0, 1), (1, 2 * wf4, wf4 * wf4), fs: fs, warpAt: wf4)
+        case .c:
+            s = bilinear((1, 0, 0), (1, 2 * wf1, wf1 * wf1), fs: fs)
+              + bilinear((0, 0, 1), (1, 2 * wf4, wf4 * wf4), fs: fs, warpAt: wf4)
+        case .z:
+            return [1, 0, 0, 0, 0]                         // flat, one pass-through section
+        }
+        let g = 1.0 / cascadeResponse(s, 1000.0, fs: fs)
+        s[0] *= g; s[1] *= g; s[2] *= g
+        return s
+    }
+}
+
+/// A weighting filter bound to one channel. The coefficients could be shared
+/// but the delay line cannot, and a setup per channel costs a few hundred
+/// bytes — not worth the aliasing risk of sharing one.
+final class WeightingFilter {
+    private let setup: vDSP_biquad_Setup
+    private var delay: [Float]
+    private let sections: vDSP_Length
+
+    init(_ weighting: Weighting, fs: Double) {
+        let coeffs = weighting.sections(fs: fs)
+        sections = vDSP_Length(coeffs.count / 5)
+        guard let s = vDSP_biquad_CreateSetup(coeffs, sections) else {
+            fail("cannot build \(weighting.rawValue)-weighting filter")
+        }
+        setup = s
+        delay = [Float](repeating: 0, count: Int(sections) * 2 + 2)
+    }
+
+    deinit { vDSP_biquad_DestroySetup(setup) }
+
+    func process(_ input: UnsafePointer<Float>, _ output: inout [Float], _ n: Int) {
+        vDSP_biquad(setup, &delay, input, 1, &output, 1, vDSP_Length(n))
+    }
+}
+
+/* ── third-octave band plan for the RTA ─────────────────────────────── */
+
+/// The wire always carries 1/48-octave bands, and a tile folds them down to
+/// whatever banding it wants to draw.
+///
+/// That works exactly because every banding the dashboard offers divides 48:
+/// 1/3 is sixteen of these summed, 1/6 is eight, 1/12 four, 1/24 two. Powers
+/// are additive, so a fold is a sum and nothing is approximated. The
+/// alternative — the capture re-banding on request — would mean one dashboard
+/// choosing 1/6 changes what every other dashboard sees.
+///
+/// Band n is centred on 1000 · 2^(n/48); n = 0 is 1 kHz, which is what keeps
+/// the folded centres on the standard values.
+let bandN0 = -271                                     // ≈ 20 Hz
+let bandN1 = 207                                      // ≈ 20 kHz
+let bandCentres: [Double] = (bandN0...bandN1).map { 1000 * pow(2, Double($0) / 48) }
+
+/// FFT bin ranges per band, clamped to what the transform can actually
+/// resolve.
+///
+/// This is the one caveat a reader of the RTA needs and the gear is not
+/// allowed to carry (module rule 5, no explanatory text in a tile's
+/// settings): below roughly 200 Hz a 1/48-octave band is narrower than one
+/// bin, so neighbouring bands start sharing bins and the low end reads
+/// smoother than it really is. That is the window length talking, not the
+/// room. Folding to 1/6 or 1/3 puts it right, and a multi-resolution
+/// transform is the real fix if the bottom octaves ever have to be read at
+/// full resolution.
+func bandBins(fs: Double, fftSize: Int) -> [(Int, Int)] {
+    let binHz = fs / Double(fftSize)
+    let maxBin = fftSize / 2 - 1
+    return bandCentres.map { fc in
+        let lo = Int((fc * pow(2, -1.0 / 96.0) / binHz).rounded())
+        let hi = Int((fc * pow(2, 1.0 / 96.0) / binHz).rounded())
+        return (max(1, min(lo, maxBin)), max(1, min(max(hi, lo), maxBin)))
+    }
+}
+
+/* ── per-channel measurement state ──────────────────────────────────── */
+
+/// Everything the standard asks for on one channel.
+///
+/// SPL is an exponential moving average of weighted mean square — Fast is a
+/// 125 ms time constant, Slow 1 s, exactly as IEC 61672 defines them. Leq is
+/// a plain energy average with no time constant at all, which is why it is
+/// accumulated separately rather than read off the integrator.
+final class ChannelMeter {
+    let index: Int                      // 1-based, as the operator counts them
+    private let fs: Double
+    private let calibration: Double     // dB added to turn dBFS into dB SPL
+
+    private let weightFilter: WeightingFilter
+    private let cFilter: WeightingFilter
+    private var weighted: [Float]
+    private var cWeighted: [Float]
+
+    // One integrator per averaging the dashboard might ask for. They all run
+    // all the time and all go on the wire: a tile choosing "Slow" must not
+    // restart capture, because the next tile wants "Fast" off the same
+    // stream and a third wants Inf. Four extra doubles per channel is a
+    // rounding error next to the filtering; re-measuring per viewer is not.
+    private var msFast: Double = 0
+    private var msSlow: Double = 0
+    private var msNone: Double = 0           // this block only, no time constant
+    private var flatMeanSquare: Double = 0   // unweighted, Fast — for dBFS
+    private let alphaFast: Double
+    private let alphaSlow: Double
+
+    // Leq accumulators: running since reset, plus rolling 1 and 10 minute.
+    private var leqSum: Double = 0
+    private var leqCount: Double = 0
+    private var ring: [Double] = []     // one mean-square per emitted frame
+    private let ringCapacity: Int
+
+    private var peakC: Double = 0       // linear, since reset
+    private var peakZ: Double = 0
+    private var clipped = false
+
+    init(index: Int, fs: Double, weighting: Weighting, calibration: Double,
+         framesPerSecond: Double) {
+        self.index = index
+        self.fs = fs
+        self.calibration = calibration
+        weightFilter = WeightingFilter(weighting, fs: fs)
+        cFilter = WeightingFilter(.c, fs: fs)
+        weighted = []
+        cWeighted = []
+        // The time constants IEC 61672 names: Fast is 125 ms, Slow is 1 s.
+        alphaFast = 1.0 - exp(-1.0 / (0.125 * fs))
+        alphaSlow = 1.0 - exp(-1.0 / (1.0 * fs))
+        ringCapacity = Int((600.0 * framesPerSecond).rounded())   // 10 minutes
+    }
+
+    /// Feed one tap buffer for this channel.
+    func push(_ samples: UnsafePointer<Float>, _ n: Int) {
+        if weighted.count < n {
+            weighted = [Float](repeating: 0, count: n)
+            cWeighted = [Float](repeating: 0, count: n)
+        }
+        weightFilter.process(samples, &weighted, n)
+        cFilter.process(samples, &cWeighted, n)
+
+        // Exponential integration over the weighted signal, sample by sample
+        // in the power domain. vDSP has no one-pole on squares, and at 48 kHz
+        // this is a few hundred thousand multiply-adds a second — noise next
+        // to the filtering above.
+        var fast = msFast, slow = msSlow, flat = flatMeanSquare
+        weighted.withUnsafeBufferPointer { w in
+            for i in 0..<n {
+                let v = Double(w[i]) * Double(w[i])
+                fast += alphaFast * (v - fast)
+                slow += alphaSlow * (v - slow)
+                let r = Double(samples[i])
+                flat += alphaFast * (r * r - flat)
+            }
+        }
+        msFast = fast; msSlow = slow; flatMeanSquare = flat
+
+        // Mean square of just this block — "None", the reading with no time
+        // constant at all. Also what Leq accumulates, since Leq is a plain
+        // energy average and has no time constant either.
+        var sumSq: Float = 0
+        weighted.withUnsafeBufferPointer { w in
+            vDSP_measqv(w.baseAddress!, 1, &sumSq, vDSP_Length(n))
+        }
+        msNone = Double(sumSq)
+        leqSum += Double(sumSq) * Double(n)
+        leqCount += Double(n)
+
+        var cPeak: Float = 0, zPeak: Float = 0
+        cWeighted.withUnsafeBufferPointer { c in
+            vDSP_maxmgv(c.baseAddress!, 1, &cPeak, vDSP_Length(n))
+        }
+        vDSP_maxmgv(samples, 1, &zPeak, vDSP_Length(n))
+        peakC = max(peakC, Double(cPeak))
+        peakZ = max(peakZ, Double(zPeak))
+        if zPeak >= 0.999 { clipped = true }
+    }
+
+    /// dB SPL from a linear mean-square, with the calibration offset applied.
+    private func db(_ power: Double) -> Double {
+        20 * log10(max(power, 1e-20).squareRoot()) + calibration
+    }
+
+    /// Called once per emitted frame; also advances the rolling Leq window.
+    ///
+    /// Returns a JSON object built by hand. JSONSerialization renders a
+    /// rounded Double as `-70.120000000000005`, which is both ugly on the
+    /// wire and noise in a diff — `%.2f` says what a meter can actually
+    /// resolve and nothing more.
+    func snapshot() -> String {
+        ring.append(msNone)
+        if ring.count > ringCapacity { ring.removeFirst(ring.count - ringCapacity) }
+
+        let fps = Double(ringCapacity) / 600.0
+        func rollingLeq(seconds: Double) -> Double {
+            let want = max(1, Int((seconds * fps).rounded()))
+            let slice = ring.suffix(want)
+            guard !slice.isEmpty else { return -200 }
+            return db(slice.reduce(0, +) / Double(slice.count))
+        }
+
+        return "{\"i\":\(index)"
+            + f("fast", db(msFast))
+            + f("slow", db(msSlow))
+            + f("inf", leqCount > 0 ? db(leqSum / leqCount) : -200)
+            + f("none", db(msNone))
+            + f("leq1m", rollingLeq(seconds: 60))
+            + f("leq10m", rollingLeq(seconds: 600))
+            + f("peakC", db(peakC * peakC))
+            + f("peakZ", db(peakZ * peakZ))
+            + f("dbfs", 20 * log10(max(flatMeanSquare, 1e-20).squareRoot()))
+            + ",\"clip\":\(clipped)}"
+    }
+
+    /// Clears Leq, peaks and the clip flag. The exponential integrator is
+    /// deliberately left alone — it is a live reading, not an accumulation,
+    /// and zeroing it would just make the meter dive for a moment.
+    func reset() {
+        leqSum = 0; leqCount = 0; ring.removeAll(keepingCapacity: true)
+        peakC = 0; peakZ = 0; clipped = false
+    }
+}
+
+/// `,"key":-12.34` — two decimals, and a floor instead of -inf or NaN so a
+/// silent input can never put a non-number on the wire.
+func f(_ key: String, _ v: Double) -> String {
+    ",\"\(key)\":" + num(v)
+}
+
+func num(_ v: Double) -> String {
+    guard v.isFinite else { return "-200.00" }
+    return String(format: "%.2f", max(v, -200))
+}
+
+/// One decimal, for band arrays. 479 bands per channel per frame is the
+/// bulk of the wire; a second decimal on a bar nobody can read that finely
+/// is 15% of the bandwidth for nothing.
+func num1(_ v: Double) -> String {
+    guard v.isFinite else { return "-200" }
+    return String(format: "%.1f", max(v, -200))
+}
+
+/* ── spectrum for the RTA / spectrograph tiles ──────────────────────── */
+
+final class Spectrum {
+    private let fftSize: Int
+    private let log2n: vDSP_Length
+    private let setup: FFTSetup
+    private var window: [Float]
+    private var accum: [Float]           // sliding input buffer
+    private var filled = 0
+    private let bins: [(Int, Int)]
+    private let windowPower: Double
+
+    init(fs: Double, fftSize: Int) {
+        self.fftSize = fftSize
+        log2n = vDSP_Length(log2(Double(fftSize)).rounded())
+        guard let s = vDSP_create_fftsetup(log2n, FFTRadix(kFFTRadix2)) else {
+            fail("cannot create FFT setup")
+        }
+        setup = s
+        window = [Float](repeating: 0, count: fftSize)
+        vDSP_hann_window(&window, vDSP_Length(fftSize), Int32(vDSP_HANN_DENORM))
+        accum = [Float](repeating: 0, count: fftSize)
+        bins = bandBins(fs: fs, fftSize: fftSize)
+        // Coherent gain of the Hann window, so band levels are not 6 dB low.
+        windowPower = window.reduce(0.0) { $0 + Double($1) * Double($1) } / Double(fftSize)
+    }
+
+    deinit { vDSP_destroy_fftsetup(setup) }
+
+    /// Keep the most recent `fftSize` samples, shifting the window along.
+    /// Buffers larger than the window just overwrite it outright.
+    func push(_ samples: UnsafePointer<Float>, _ n: Int) {
+        if n >= fftSize {
+            accum.withUnsafeMutableBufferPointer { a in
+                a.baseAddress!.update(from: samples + (n - fftSize), count: fftSize)
+            }
+            filled = fftSize
+            return
+        }
+        accum.withUnsafeMutableBufferPointer { a in
+            let base = a.baseAddress!
+            // Slide the old tail down, then append the new block.
+            base.update(from: base + n, count: fftSize - n)
+            (base + fftSize - n).update(from: samples, count: n)
+        }
+        filled = min(fftSize, filled + n)
+    }
+
+    /// Third-octave band levels in dB relative to full scale, plus the
+    /// calibration offset applied by the caller.
+    func bands(calibration: Double) -> [Double] {
+        guard filled >= fftSize else { return bins.map { _ in -200 } }
+        var windowed = [Float](repeating: 0, count: fftSize)
+        vDSP_vmul(accum, 1, window, 1, &windowed, 1, vDSP_Length(fftSize))
+
+        let half = fftSize / 2
+        var re = [Float](repeating: 0, count: half)
+        var im = [Float](repeating: 0, count: half)
+        var mag = [Float](repeating: 0, count: half)
+        re.withUnsafeMutableBufferPointer { rp in
+            im.withUnsafeMutableBufferPointer { ip in
+                var split = DSPSplitComplex(realp: rp.baseAddress!, imagp: ip.baseAddress!)
+                windowed.withUnsafeBytes { raw in
+                    vDSP_ctoz(raw.bindMemory(to: DSPComplex.self).baseAddress!, 2,
+                              &split, 1, vDSP_Length(half))
+                }
+                vDSP_fft_zrip(setup, &split, 1, log2n, FFTDirection(FFT_FORWARD))
+                vDSP_zvmags(&split, 1, &mag, 1, vDSP_Length(half))
+            }
+        }
+        // vDSP's real FFT carries a factor of 2, and zvmags squares it.
+        let scale = 1.0 / (4.0 * Double(fftSize) * Double(fftSize) * windowPower)
+        return bins.map { (lo, hi) in
+            var power = 0.0
+            for b in lo...hi { power += Double(mag[b]) }
+            power *= scale * 2.0                       // one-sided spectrum
+            return 10 * log10(max(power, 1e-20)) + calibration
+        }
+    }
+}
+
+/* ── args ───────────────────────────────────────────────────────────── */
+
+var wantList = false
+var wantSelftest = false
+var wantDevice: String? = nil
+var wantChannels: [Int] = [1]
+var wantCal: [Double] = []
+var wantWeighting = Weighting.a
+var wantBands = false
+var framesPerSecond = 20.0
+
+let argv = CommandLine.arguments
+var argIdx = 1
+func nextArg(_ flag: String) -> String {
+    argIdx += 1
+    guard argIdx < argv.count else { fail("\(flag) needs a value") }
+    return argv[argIdx]
+}
+while argIdx < argv.count {
+    switch argv[argIdx] {
+    case "--list": wantList = true
+    case "--selftest": wantSelftest = true
+    case "--device": wantDevice = nextArg("--device")
+    case "--channels":
+        wantChannels = nextArg("--channels").split(separator: ",").compactMap { Int($0.trimmingCharacters(in: .whitespaces)) }
+        if wantChannels.isEmpty { fail("--channels needs at least one 1-based channel number") }
+    case "--cal":
+        wantCal = nextArg("--cal").split(separator: ",").compactMap { Double($0.trimmingCharacters(in: .whitespaces)) }
+    case "--weighting":
+        let raw = nextArg("--weighting").uppercased()
+        guard let w = Weighting(rawValue: raw) else { fail("--weighting must be A, C or Z") }
+        wantWeighting = w
+    case "--bands": wantBands = true
+    case "--rate":
+        guard let r = Double(nextArg("--rate")), r >= 1, r <= 50 else { fail("--rate must be 1-50 (frames per second)") }
+        framesPerSecond = r
+    default: fail("unknown flag \(argv[argIdx]) — try --list")
+    }
+    argIdx += 1
+}
+
+/* ── selftest: prove the weighting curves before trusting a reading ─── */
+
+if wantSelftest {
+    // IEC 61672-1 table 3, nominal A- and C-weighting.
+    let table: [(Double, Double, Double)] = [
+        (31.5, -39.4, -3.0), (63, -26.2, -0.8), (125, -16.1, -0.2), (250, -8.6, 0.0),
+        (500, -3.2, 0.0), (1000, 0.0, 0.0), (2000, 1.2, -0.2), (4000, 1.0, -0.8),
+        (8000, -1.1, -3.0), (16000, -6.6, -8.5),
+    ]
+    for fs in [48000.0, 96000.0] {
+        let a = Weighting.a.sections(fs: fs), c = Weighting.c.sections(fs: fs)
+        print("— \(Int(fs)) Hz —")
+        print("    Hz        A      IEC     err        C      IEC     err")
+        var worstA = 0.0, worstC = 0.0
+        for (f, wantA, wantC) in table where f < fs / 2 {
+            let gotA = 20 * log10(cascadeResponse(a, f, fs: fs))
+            let gotC = 20 * log10(cascadeResponse(c, f, fs: fs))
+            worstA = max(worstA, abs(gotA - wantA)); worstC = max(worstC, abs(gotC - wantC))
+            print(String(format: "%7.0f  %+7.2f  %+7.2f  %+6.2f   %+7.2f  %+7.2f  %+6.2f",
+                         f, gotA, wantA, gotA - wantA, gotC, wantC, gotC - wantC))
+        }
+        print(String(format: "  worst: A %.2f dB, C %.2f dB\n", worstA, worstC))
+    }
+    exit(0)
+}
+
+/* ── device selection ───────────────────────────────────────────────── */
+
+let devices = listInputDevices()
+
+if wantList || wantDevice == nil {
+    if devices.isEmpty { fail("no input-capable audio devices found") }
+    // stdout, as JSON: the module's /devices route feeds this straight to
+    // the admin page's device picker.
+    let payload = devices.map { ["name": $0.name, "uid": $0.uid,
+                                 "channels": $0.channels, "sampleRate": $0.sampleRate] }
+    let data = try! JSONSerialization.data(withJSONObject: ["devices": payload])
+    FileHandle.standardOutput.write(data)
+    FileHandle.standardOutput.write("\n".data(using: .utf8)!)
+    if wantDevice == nil && !wantList { note("pick one with --device <name substring>") }
+    exit(wantList ? 0 : 2)
+}
+
+let query = wantDevice!.lowercased()
+let exact = devices.filter { $0.name.lowercased() == query || $0.uid.lowercased() == query }
+let matches = exact.count == 1 ? exact
+    : devices.filter { $0.name.lowercased().contains(query) || $0.uid.lowercased().contains(query) }
+guard matches.count == 1 else {
+    if matches.isEmpty { fail("no input device matches \"\(wantDevice!)\" — see --list") }
+    fail("\"\(wantDevice!)\" is ambiguous: " + matches.map { $0.name }.joined(separator: ", "))
+}
+let device = matches[0]
+
+/* ── capture ────────────────────────────────────────────────────────── */
+
+let engine = AVAudioEngine()
+guard let unit = engine.inputNode.audioUnit else { fail("no input audio unit") }
+var deviceID = device.id
+let setErr = AudioUnitSetProperty(unit, kAudioOutputUnitProperty_CurrentDevice,
+                                  kAudioUnitScope_Global, 0, &deviceID,
+                                  UInt32(MemoryLayout<AudioDeviceID>.size))
+guard setErr == noErr else { fail("cannot select \"\(device.name)\" (error \(setErr))") }
+
+let format = engine.inputNode.inputFormat(forBus: 0)
+let channelCount = Int(format.channelCount)
+let sampleRate = format.sampleRate
+guard channelCount > 0, sampleRate > 0 else {
+    fail("\"\(device.name)\" reports no usable input format — microphone access may be denied "
+        + "(System Settings → Privacy & Security → Microphone)")
+}
+for ch in wantChannels where ch < 1 || ch > channelCount {
+    fail("channel \(ch) is out of range — \"\(device.name)\" has \(channelCount)")
+}
+
+let calibrated = !wantCal.isEmpty
+if calibrated && wantCal.count != wantChannels.count {
+    fail("--cal needs one offset per channel (\(wantChannels.count) given \(wantCal.count))")
+}
+
+let meters = wantChannels.enumerated().map { (i, ch) in
+    ChannelMeter(index: ch, fs: sampleRate, weighting: wantWeighting,
+                 calibration: calibrated ? wantCal[i] : 0, framesPerSecond: framesPerSecond)
+}
+let spectra = wantBands ? wantChannels.map { _ in Spectrum(fs: sampleRate, fftSize: 16384) } : []
+
+note("capturing \"\(device.name)\": \(channelCount) channels @ \(Int(sampleRate)) Hz, "
+    + "measuring \(wantChannels.map(String.init).joined(separator: ",")) "
+    + "\(wantWeighting.rawValue)-weighted"
+    + (calibrated ? "" : ", UNCALIBRATED"))
+
+// Announced once so the reader knows the band plan without hardcoding it.
+let hello: [String: Any] = [
+    "hello": 1,
+    "device": device.name,
+    "sampleRate": sampleRate,
+    "deviceChannels": channelCount,
+    "channels": wantChannels,
+    "weighting": wantWeighting.rawValue,
+    "calibrated": calibrated,
+    // Centres and the index of the 1 kHz band, so a tile can fold to any
+    // banding without hardcoding the plan.
+    "bands": wantBands ? bandCentres.map { round($0 * 100) / 100 } : [],
+    "bandN0": bandN0,
+    "bandsPerOctave": 48,
+]
+let stdoutHandle = FileHandle.standardOutput
+func emitLine(_ json: String) {
+    do {
+        try stdoutHandle.write(contentsOf: Data((json + "\n").utf8))
+    } catch { exit(0) }                 // downstream pipe closed — nothing to say
+}
+if let data = try? JSONSerialization.data(withJSONObject: hello),
+   let line = String(data: data, encoding: .utf8) {
+    emitLine(line)
+}
+
+// A reset is asked for on stdin (one line, "reset") rather than a signal, so
+// the listener can clear Leq and peaks without restarting capture and losing
+// the filters' settling.
+let resetQueue = DispatchQueue(label: "spl-capture.reset")
+var resetRequested = false
+DispatchQueue.global().async {
+    while let line = readLine(strippingNewline: true) {
+        if line.trimmingCharacters(in: .whitespaces).lowercased() == "reset" {
+            resetQueue.sync { resetRequested = true }
+        }
+    }
+}
+
+let tapQueue = DispatchQueue(label: "spl-capture.tap")
+engine.inputNode.installTap(onBus: 0, bufferSize: 2048, format: format) { buffer, _ in
+    let frames = Int(buffer.frameLength)
+    guard frames > 0, let floats = buffer.floatChannelData else { return }
+    tapQueue.sync {
+        for (i, ch) in wantChannels.enumerated() {
+            let src = floats[ch - 1]                 // tap data is per-channel, not interleaved
+            meters[i].push(src, frames)
+            if wantBands { spectra[i].push(src, frames) }
+        }
+    }
+}
+
+do { try engine.start() } catch {
+    fail("engine start failed: \(error.localizedDescription) — if this is a permission problem, "
+        + "approve microphone access for the launching app and retry")
+}
+
+let timer = DispatchSource.makeTimerSource(queue: DispatchQueue.global())
+timer.schedule(deadline: .now() + 1.0 / framesPerSecond,
+               repeating: 1.0 / framesPerSecond)
+timer.setEventHandler {
+    var wantReset = false
+    resetQueue.sync { wantReset = resetRequested; resetRequested = false }
+
+    var line = "{\"t\":\(Int(Date().timeIntervalSince1970 * 1000))"
+    tapQueue.sync {
+        if wantReset { meters.forEach { $0.reset() } }
+        line += ",\"ch\":[" + meters.map { $0.snapshot() }.joined(separator: ",") + "]"
+        if wantBands {
+            let sets = spectra.enumerated().map { (i, s) -> String in
+                "[" + s.bands(calibration: calibrated ? wantCal[i] : 0)
+                    .map(num1).joined(separator: ",") + "]"
+            }
+            line += ",\"bands\":[" + sets.joined(separator: ",") + "]"
+        }
+    }
+    emitLine(line + "}")
+}
+timer.resume()
+
+signal(SIGINT) { _ in exit(0) }
+signal(SIGTERM) { _ in exit(0) }
+RunLoop.main.run()

modules/spl-meter/spl-listener.js

@@ -0,0 +1,239 @@
+'use strict';
+
+/**
+ * Sound level listener — owns the native capture child.
+ *
+ * Spawns spl-capture (compiled from spl-capture.swift beside it) for the
+ * admin-configured device and channels, reads its JSON lines, and hands the
+ * latest frame upward. All measurement happens in the child; this file is
+ * plumbing and supervision, nothing more.
+ *
+ * Reports via onUpdate:
+ *
+ *   { frame: {...}, meta: {...} }     measuring
+ *   { error: '<what is wrong and how to fix it>' }   not measuring
+ *
+ * The capture binary is per-machine and gitignored, exactly like the Timers
+ * module's ltc-capture. It normally arrives already built — compiled beside
+ * the app, or copied from any Mac of the same architecture. When it is
+ * missing this will build it, but in the background and never on the event
+ * loop: see ensureBinary for what that cost the first time it was wrong.
+ *
+ * The same macOS gotcha applies as for LTC, and is worth repeating because
+ * it costs an afternoon every time: a ProdDash launched over SSH or from a
+ * bare launchd job gets SILENT ZEROS from every input, with no error
+ * anywhere. Here that shows up as a meter pinned at -200. Launch from a
+ * logged-in GUI context and approve the microphone prompt once.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+const RESTART_MS = 5000;
+/** An immediate exit is config-shaped (bad device, channel out of range) —
+    retrying every 5 s would only fill the log with the same sentence. */
+const BAD_CONFIG_RETRY_MS = 30000;
+/** No frame for this long means the child is alive but not delivering. */
+const STALL_MS = 3000;
+
+/**
+ * @param {{device:string, channels:number[], weighting:string,
+ *          bands:boolean, calibration:number[], moduleDir:string,
+ *          log:Function, onUpdate:(u:object)=>void}} opts
+ * @returns {{stop:()=>void, reset:()=>void}}
+ */
+function createSplListener(opts) {
+  const { device, channels, weighting, bands, calibration, moduleDir, log, onUpdate } = opts;
+  const bin = path.join(moduleDir, 'spl-capture');
+
+  let child = null;
+  let stopped = false;
+  let restartTimer = null;
+  let stallTimer = null;
+  let startedAt = 0;
+  let meta = null;
+  let building = false;
+  let buildFailed = false;
+  let lastFrameWall = 0;
+
+  const BUILD_HELP = 'Sound level capture tool missing — build it on any Apple Silicon Mac with '
+    + '`swiftc -O -o modules/spl-meter/spl-capture modules/spl-meter/spl-capture.swift` '
+    + 'and copy it next to spl-capture.swift';
+
+  /**
+   * Build the capture tool if it is missing, WITHOUT blocking.
+   *
+   * This used to be a spawnSync, copied from the LTC listener where the
+   * source is a third the size and builds in a few seconds. Here it took
+   * nearly two minutes on the production Mac and froze the entire ProdDash
+   * server for every second of it — one module's optional helper took the
+   * whole dashboard down, then did it again on every retry. Nothing that
+   * runs while a service might be on is allowed to hold the event loop.
+   *
+   * The build is a fallback for a module installed from the catalog on a
+   * machine with a Swift toolchain. The normal path is a binary built
+   * alongside the app, or copied from any same-architecture Mac.
+   *
+   * @returns {string} '' when the binary is ready, otherwise what to say.
+   */
+  function ensureBinary() {
+    if (fs.existsSync(bin)) return '';
+    const src = bin + '.swift';
+    if (!fs.existsSync(src)) return 'spl-capture.swift is missing from the module folder';
+    if (building) return 'Building the capture tool — this takes a minute or two';
+    if (buildFailed) return BUILD_HELP;
+
+    building = true;
+    log('spl-capture binary missing — building it in the background');
+    const build = spawn('swiftc', ['-O', '-o', bin, src], { stdio: ['ignore', 'ignore', 'pipe'] });
+    let buildErr = '';
+    build.stderr.setEncoding('utf8');
+    build.stderr.on('data', (t) => { buildErr = (buildErr + t).slice(-800); });
+    const giveUp = setTimeout(() => {
+      try { build.kill('SIGKILL'); } catch { /* already gone */ }
+    }, 300000);
+    build.on('error', (err) => {
+      clearTimeout(giveUp);
+      building = false; buildFailed = true;
+      log(`swiftc could not be run: ${err.message}`);
+    });
+    build.on('exit', (code) => {
+      clearTimeout(giveUp);
+      building = false;
+      if (code === 0 && fs.existsSync(bin)) {
+        log('spl-capture built');
+        buildFailed = false;
+        if (!stopped) { clearTimeout(restartTimer); restartTimer = null; start(); }
+        return;
+      }
+      buildFailed = true;
+      log(`spl-capture build failed (exit ${code})` + (buildErr ? `: ${buildErr.trim().split('\n').pop()}` : ''));
+    });
+    return 'Building the capture tool — this takes a minute or two';
+  }
+
+  function scheduleRestart(ms) {
+    if (stopped || restartTimer) return;
+    restartTimer = setTimeout(() => { restartTimer = null; start(); }, ms);
+  }
+
+  function armStallWatch() {
+    clearTimeout(stallTimer);
+    stallTimer = setTimeout(() => {
+      if (stopped || !child) return;
+      if (Date.now() - lastFrameWall >= STALL_MS) {
+        log('no frames for 3 s — restarting capture');
+        try { child.kill('SIGTERM'); } catch { /* already gone */ }
+      }
+    }, STALL_MS);
+  }
+
+  function start() {
+    if (stopped) return;
+
+    const missing = ensureBinary();
+    if (missing) {
+      onUpdate({ error: missing });
+      // A build in flight calls start() itself when it lands; anything else
+      // is config-shaped and should back off hard rather than spin.
+      if (!building) scheduleRestart(BAD_CONFIG_RETRY_MS);
+      return;
+    }
+
+    // No averaging or banding flag: the child computes every averaging and
+    // the finest banding regardless, so tiles can differ without a restart.
+    const args = ['--device', device, '--channels', channels.join(','),
+                  '--weighting', weighting, '--rate', '20'];
+    if (bands) args.push('--bands');
+    if (calibration.length === channels.length) args.push('--cal', calibration.join(','));
+
+    startedAt = Date.now();
+    meta = null;
+    let stderrTail = '';
+    let buf = '';
+
+    child = spawn(bin, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (text) => {
+      stderrTail = (stderrTail + text).slice(-500);
+    });
+
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (text) => {
+      buf += text;
+      let i;
+      while ((i = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, i).trim();
+        buf = buf.slice(i + 1);
+        if (!line) continue;
+        let obj;
+        try { obj = JSON.parse(line); } catch { continue; }
+        if (obj.hello) {
+          meta = obj;
+          log(`measuring ${obj.device} ch ${obj.channels.join(',')} `
+            + `${obj.weighting}-weighted`
+            + (obj.calibrated ? '' : ' (uncalibrated)'));
+          continue;
+        }
+        if (!obj.ch) continue;
+        lastFrameWall = Date.now();
+        armStallWatch();
+        onUpdate({ frame: obj, meta });
+      }
+      // A run of junk with no newline would grow forever; the child never
+      // emits a line this long, so anything that does is a bug upstream.
+      if (buf.length > 65536) buf = '';
+    });
+
+    child.on('error', (err) => {
+      onUpdate({ error: `cannot run spl-capture: ${err.message}` });
+      child = null;
+      scheduleRestart(BAD_CONFIG_RETRY_MS);
+    });
+
+    child.on('exit', (code, signal) => {
+      child = null;
+      clearTimeout(stallTimer);
+      if (stopped) return;
+      const ranFor = Date.now() - startedAt;
+      const why = stderrTail.trim().split('\n').pop() || `exit ${code}${signal ? ' ' + signal : ''}`;
+      // Exiting almost immediately means it never got as far as capturing —
+      // an unknown device, an out-of-range channel, a denied microphone.
+      // Those do not fix themselves, so back off hard and say why.
+      if (ranFor < 2000) {
+        onUpdate({ error: why });
+        scheduleRestart(BAD_CONFIG_RETRY_MS);
+      } else {
+        log(`capture exited after ${Math.round(ranFor / 1000)}s: ${why}`);
+        scheduleRestart(RESTART_MS);
+      }
+    });
+
+    armStallWatch();
+  }
+
+  start();
+
+  return {
+    /** Clear Leq and peak hold without restarting capture — the filters keep
+        their settling, so the live number never dips. */
+    reset() {
+      if (child && child.stdin.writable) {
+        try { child.stdin.write('reset\n'); } catch { /* child going away */ }
+      }
+    },
+    stop() {
+      stopped = true;
+      clearTimeout(restartTimer); restartTimer = null;
+      clearTimeout(stallTimer); stallTimer = null;
+      if (child) {
+        try { child.kill('SIGTERM'); } catch { /* already gone */ }
+        child = null;
+      }
+    },
+  };
+}
+
+module.exports = { createSplListener };

modules/spl-meter/style.css

@@ -0,0 +1,154 @@
+/* SPL Meter — every colour comes from the shell's variables so themes and
+   per-tile tints reach in. Nothing here is hardcoded except the canvas
+   heat ramp, which client.js owns because it has to interpolate. */
+
+[data-module="spl-meter"] .spl {
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+/* ── readout ──────────────────────────────────────────────────────── */
+
+[data-module="spl-meter"] .spl-readout {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.25em;
+  min-height: 0;
+  padding: 0.25rem;
+}
+
+[data-module="spl-meter"] .spl-value {
+  display: flex;
+  align-items: baseline;
+  gap: 0.2em;
+  line-height: 1;
+  color: var(--text);
+}
+
+/* A first-paint size only. client.js measures the text and sets the real
+   one inline, because CSS has to assume a digit count and gets it wrong the
+   moment the reading needs a sixth character: the coefficient that fills a
+   tile for "-45.9" pushes "-100.5" straight out through the side. */
+[data-module="spl-meter"] .spl-num {
+  font-size: clamp(1.25rem, min(26cqw, 60cqh), 100rem);
+  font-variant-numeric: tabular-nums;
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+
+[data-module="spl-meter"] .spl-unit {
+  font-size: clamp(0.65rem, min(7cqw, 15cqh), 26rem);
+  color: var(--muted);
+}
+
+[data-module="spl-meter"] .spl-sub {
+  font-size: 0.7rem;
+  color: var(--muted);
+  text-align: center;
+  line-height: 1.3;
+}
+
+[data-module="spl-meter"] .spl-readout[data-level="warn"] .spl-num { color: var(--warn); }
+[data-module="spl-meter"] .spl-readout[data-level="alarm"] .spl-num { color: var(--danger); }
+[data-module="spl-meter"] .spl-readout[data-level="idle"] .spl-num { color: var(--muted); }
+
+/* A dead input reads danger, not muted: silence that is a fault should not
+   look like silence that is a quiet room. */
+[data-module="spl-meter"] .spl-readout[data-level="dead"] .spl-num { color: var(--danger); }
+[data-module="spl-meter"] .spl-readout[data-level="dead"] .spl-sub { color: var(--danger); }
+
+/* ── level bars ───────────────────────────────────────────────────── */
+
+[data-module="spl-meter"] .spl-bars {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  gap: 0.35rem;
+  padding: 0.4rem;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+[data-module="spl-meter"] .spl-bar {
+  display: grid;
+  grid-template-columns: 1.4em 1fr 3.4em;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.75rem;
+}
+
+[data-module="spl-meter"] .spl-bar-label { color: var(--muted); text-align: right; }
+
+[data-module="spl-meter"] .spl-bar-track {
+  position: relative;
+  height: 0.65rem;
+  border-radius: 0.35rem;
+  background: color-mix(in srgb, var(--border) 60%, transparent);
+  overflow: hidden;
+}
+
+[data-module="spl-meter"] .spl-bar-fill {
+  position: absolute;
+  inset: 0 auto 0 0;
+  width: 0;
+  border-radius: inherit;
+  background: var(--accent);
+  transition: width 60ms linear;
+}
+
+[data-module="spl-meter"] .spl-bar[data-level="warn"] .spl-bar-fill { background: var(--warn); }
+[data-module="spl-meter"] .spl-bar[data-level="alarm"] .spl-bar-fill { background: var(--danger); }
+[data-module="spl-meter"] .spl-bar[data-level="idle"] .spl-bar-fill { background: var(--muted); }
+[data-module="spl-meter"] .spl-bar[data-level="dead"] .spl-bar-value { color: var(--danger); }
+
+/* Peak hold sits on the track rather than inside the fill, so it stays
+   visible when the bar falls away underneath it. */
+[data-module="spl-meter"] .spl-bar-peak {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background: var(--text);
+  opacity: 0.75;
+}
+
+[data-module="spl-meter"] .spl-bar-value {
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+  color: var(--text);
+}
+
+[data-module="spl-meter"] .spl-bar.clip .spl-bar-value { color: var(--danger); }
+
+/* ── canvas tiles ─────────────────────────────────────────────────── */
+
+[data-module="spl-meter"] .spl-canvas {
+  flex: 1;
+  display: block;
+  width: 100%;
+  min-height: 0;
+  border-radius: 0.25rem;
+}
+
+/* The readout scales off both of the tile's dimensions, so the container
+   has to be sized on both axes — inline-size alone leaves cqh undefined. */
+[data-module="spl-meter"] .spl { container-type: size; }
+
+/* The sub-line is the first thing to go when the tile gets short: the
+   number is the point, and a clipped caption under it is worse than none. */
+[data-module="spl-meter"] .spl-sub {
+  max-width: 100%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+@container (max-height: 90px) {
+  [data-module="spl-meter"] .spl-sub { display: none; }
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "proddash",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "private": true,
   "description": "Modular production dashboard for Waters Church \u2014 zero-dependency Node server + vanilla client",
   "license": "UNLICENSED",

public/admin/admin.js

@@ -909,7 +909,25 @@ async function loadLayouts() {
         else toast(e.message, true);
       }
     });
-    row.append(name, meta, rename, del);
+    // The copy the last save replaced, one back. Restoring swaps the two,
+    // so a restore is itself one restore away from being undone.
+    const restore = document.createElement('button');
+    restore.className = 'btn';
+    restore.textContent = 'Restore previous';
+    restore.title = 'Put back the copy the last save replaced';
+    restore.hidden = !layout.hasPrevious;
+    restore.addEventListener('click', async () => {
+      if (!confirm(`Go back to the previous version of “${layout.name}”? The current one becomes its previous version, so this can be undone the same way.`)) return;
+      try {
+        await api(`/api/layouts/${encodeURIComponent(layout.name)}/restore`, { method: 'POST', body: '{}' });
+        toast('Previous version restored');
+        loadLayouts();
+      } catch (e) {
+        if (e.authRequired) showLogin();
+        else toast(e.message, true);
+      }
+    });
+    row.append(name, meta, restore, rename, del);
     layoutsList.appendChild(row);
   }
 }

public/shell.js

@@ -5,7 +5,18 @@
    settings) autosaves to this browser's localStorage — every browser is fully
    independent. Modules render inside tile bodies and never touch the shell.  */
 
-const COLS = 12;
+/* ── grid density ─────────────────────────────────────────────────────
+   How many columns the board is cut into. Twelve is the default; a finer
+   grid lets tiles be smaller and more of them fit across (a 4K wall), a
+   coarser one suits a small screen read close up. It is this browser's
+   choice — two displays at one location may want different densities — so
+   it saves with the layout, local and named, and a named layout comes back
+   at the density it was arranged on. Row height follows the column width, so
+   cells keep their shape: a 3×2 tile is still a 3×2 tile, only smaller. */
+const GRID_STEPS = [8, 10, 12, 16, 20, 24];
+const GRID_DEFAULT = 12;
+const CELL_H_DEFAULT = 72; // px per row at the default density
+let COLS = GRID_DEFAULT;
 const LS_LAYOUT = 'proddash:layout';
 
 const grid = document.getElementById('grid');
@@ -16,12 +27,24 @@ const toastEl = document.getElementById('toast');
 /* ── tiny helpers ───────────────────────────────────────────────────── */
 
 let toastTimer = null;
-function toast(msg, isError = false) {
+function toast(msg, isError = false, { action = null, ms } = {}) {
   toastEl.textContent = msg;
+  if (action) {
+    // One button, one verb — "Undo" — for a change worth taking back.
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.textContent = action.label;
+    btn.addEventListener('click', () => {
+      clearTimeout(toastTimer);
+      toastEl.hidden = true;
+      action.onClick();
+    });
+    toastEl.appendChild(btn);
+  }
   toastEl.classList.toggle('error', isError);
   toastEl.hidden = false;
   clearTimeout(toastTimer);
-  toastTimer = setTimeout(() => { toastEl.hidden = true; }, 3200);
+  toastTimer = setTimeout(() => { toastEl.hidden = true; }, ms ?? (action ? 8000 : 3200));
 }
 
 const autoHideBtn = document.getElementById('autohide-btn');
@@ -70,6 +93,41 @@ function promptModal({ title, placeholder = '', value = '', okLabel = 'Save' })
   });
 }
 
+/** A yes-or-no question in the same window: resolves true for the OK button. */
+function confirmModal({ title, body = '', okLabel = 'OK' }) {
+  return new Promise((resolve) => {
+    modalEl.innerHTML = '';
+    const h = document.createElement('h2');
+    h.textContent = title;
+    const copy = document.createElement('p');
+    copy.className = 'modal-copy';
+    copy.textContent = body;
+    const actions = document.createElement('div');
+    actions.className = 'actions';
+    const cancel = document.createElement('button');
+    cancel.className = 'btn';
+    cancel.textContent = 'Cancel';
+    const ok = document.createElement('button');
+    ok.className = 'btn primary';
+    ok.textContent = okLabel;
+    actions.append(cancel, ok);
+    modalEl.append(h, copy, actions);
+    modalBackdrop.hidden = false;
+    ok.focus();
+    const done = (result) => {
+      modalBackdrop.hidden = true;
+      modalEl.innerHTML = '';
+      resolve(result);
+    };
+    cancel.addEventListener('click', () => done(false));
+    ok.addEventListener('click', () => done(true));
+    modalEl.addEventListener('keydown', (e) => { if (e.key === 'Escape') done(false); }, { once: true });
+    modalBackdrop.addEventListener('click', (e) => {
+      if (e.target === modalBackdrop) done(false);
+    }, { once: true });
+  });
+}
+
 /* ── dropdown menus ─────────────────────────────────────────────────── */
 
 /* A menu opens the moment its button is clicked, drawn from what the page
@@ -169,17 +227,35 @@ const tileEls = new Map(); // tile id -> { el, body, dot, titleEl, instance }
    away regardless; this is the windowed equivalent, asked for by hand. */
 let autoHideHeads = false;
 
+/* Beside the layout itself: the copy it replaced (restored if the layout
+   ever fails to parse) and, after loading a named layout, the arrangement
+   that was on screen before (what Undo goes back to). */
+const LS_LAYOUT_BACKUP = LS_LAYOUT + '.backup';
+const LS_LAYOUT_PREVIOUS = LS_LAYOUT + '.previous';
+
 function saveLayout() {
   try {
-    localStorage.setItem(LS_LAYOUT, JSON.stringify({ v: 1, autoHideHeads, tiles }));
+    const next = JSON.stringify({ v: 1, autoHideHeads, gridCols: COLS, tiles });
+    const current = localStorage.getItem(LS_LAYOUT);
+    if (current && current !== next) localStorage.setItem(LS_LAYOUT_BACKUP, current);
+    localStorage.setItem(LS_LAYOUT, next);
   } catch { /* private mode / full — layout just won't persist */ }
 }
 
 function loadLayoutFromStorage() {
-  try {
-    const raw = JSON.parse(localStorage.getItem(LS_LAYOUT) || 'null');
-    if (raw && Array.isArray(raw.tiles)) return raw;
-  } catch { /* corrupted — start fresh */ }
+  for (const key of [LS_LAYOUT, LS_LAYOUT_BACKUP]) {
+    try {
+      const raw = JSON.parse(localStorage.getItem(key) || 'null');
+      if (raw && Array.isArray(raw.tiles)) {
+        // A layout that would not parse is not a reason for an empty wall.
+        if (key === LS_LAYOUT_BACKUP) {
+          toast('This browser’s layout was unreadable — the last good copy is back', true);
+          try { localStorage.setItem(LS_LAYOUT, JSON.stringify(raw)); } catch { /* fine */ }
+        }
+        return raw;
+      }
+    } catch { /* unreadable — try the copy behind it */ }
+  }
   return { tiles: [] };
 }
 
@@ -210,6 +286,87 @@ function newId() {
 
 /* ── grid geometry & collision ──────────────────────────────────────── */
 
+function normalizeGridCols(value) {
+  const n = Number(value);
+  return GRID_STEPS.includes(n) ? n : GRID_DEFAULT;
+}
+
+function cellHeightFor(cols) {
+  return Math.round((CELL_H_DEFAULT * GRID_DEFAULT) / cols);
+}
+
+/** Cut the board into `cols` columns. Tiles keep their grid units — the
+    board gets denser or coarser and everything on it changes size with it.
+    A tile now past the right edge is pulled back in, and one that would then
+    sit on another moves to the first free spot instead. */
+function setGridCols(value, { save = true } = {}) {
+  const next = normalizeGridCols(value);
+  const changed = next !== COLS;
+  COLS = next;
+  grid.style.gridTemplateColumns = `repeat(${COLS}, minmax(0, 1fr))`;
+  document.documentElement.style.setProperty('--cell-h', cellHeightFor(COLS) + 'px');
+  if (changed) {
+    // A coarser board may not have room for every tile where it was. Settle
+    // them in reading order: pull a tile past the right edge back in, and
+    // give one that would then land on a tile already settled the first free
+    // spot instead — tiles never overlap here, any more than under a drag.
+    const settled = [];
+    for (const tile of tiles.slice().sort((a, b) => a.y - b.y || a.x - b.x)) {
+      tile.w = Math.max(1, Math.min(COLS, tile.w));
+      tile.x = Math.max(0, Math.min(COLS - tile.w, tile.x));
+      if (settled.some((s) => overlaps(tile, s))) Object.assign(tile, spotAmong(tile.w, tile.h, settled));
+      settled.push(tile);
+      applyRect(tile);
+      notifyResize(tile);
+    }
+    rebuildDividers();
+    if (document.body.classList.contains('fullscreen')) applyFullscreenFit();
+  }
+  if (save) saveLayout();
+}
+
+const STEP_MINUS_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" aria-hidden="true"><path d="M5 12h14"/></svg>';
+const STEP_PLUS_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg>';
+
+/** The Layouts menu's density row — Grid Size  − 12 + — which steps without
+    closing the menu, so the board can be watched changing behind it. */
+function gridStepper() {
+  const row = document.createElement('div');
+  row.className = 'menu-stepper';
+  const label = document.createElement('span');
+  label.className = 'menu-stepper-label';
+  label.textContent = 'Grid Size';
+  const minus = document.createElement('button');
+  minus.type = 'button';
+  minus.className = 'menu-stepper-btn';
+  minus.setAttribute('data-tip', 'Coarser');
+  minus.innerHTML = STEP_MINUS_SVG;
+  const value = document.createElement('span');
+  value.className = 'menu-stepper-value';
+  const plus = document.createElement('button');
+  plus.type = 'button';
+  plus.className = 'menu-stepper-btn';
+  plus.setAttribute('data-tip', 'Finer');
+  plus.innerHTML = STEP_PLUS_SVG;
+  const paint = () => {
+    const i = GRID_STEPS.indexOf(COLS);
+    value.textContent = String(COLS);
+    minus.disabled = i <= 0;
+    plus.disabled = i >= GRID_STEPS.length - 1;
+  };
+  const step = (dir) => {
+    const i = GRID_STEPS.indexOf(COLS) + dir;
+    if (i < 0 || i >= GRID_STEPS.length) return;
+    setGridCols(GRID_STEPS[i]);
+    paint();
+  };
+  minus.addEventListener('click', () => step(-1));
+  plus.addEventListener('click', () => step(1));
+  paint();
+  row.append(label, minus, value, plus);
+  return row;
+}
+
 function cellMetrics() {
   const style = getComputedStyle(grid);
   const gapRaw = parseFloat(style.columnGap);
@@ -232,6 +389,17 @@ function isFree(rect, excludeId) {
   return isFreeExcept(rect, [excludeId]);
 }
 
+/** First spot, scanning top-to-bottom, left-to-right, clear of these tiles. */
+function spotAmong(w, h, others) {
+  for (let y = 0; y < 400; y += 1) {
+    for (let x = 0; x <= COLS - w; x += 1) {
+      const rect = { x, y, w, h };
+      if (!others.some((o) => overlaps(rect, o))) return { x, y };
+    }
+  }
+  return { x: 0, y: 0 };
+}
+
 /** First free spot scanning top-to-bottom, left-to-right. */
 function findSpot(w, h) {
   for (let y = 0; y < 200; y += 1) {
@@ -301,6 +469,72 @@ const CLOSE_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" st
 const PIN_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 16.5V22"/><path class="pin-head" d="M8.5 3h7l-1.2 7 3.2 3.2H6.5L9.7 10 8.5 3z"/></svg>';
 const GEAR_SVG = '<svg viewBox="0 0 90 90" fill="currentColor" aria-hidden="true"><path d="M 82.94 32.538 c -2.685 0 -5.093 -1.545 -6.327 -3.929 c -0.245 -0.476 -0.504 -0.948 -0.774 -1.416 c -0.27 -0.468 -0.55 -0.928 -0.84 -1.378 c -1.448 -2.26 -1.582 -5.117 -0.239 -7.443 c 1.951 -3.378 0.792 -7.696 -2.584 -9.645 l -9.352 -5.4 c -3.378 -1.951 -7.696 -0.792 -9.645 2.584 l -0.002 0.003 c -1.322 2.291 -3.815 3.641 -6.456 3.512 c -1.149 -0.056 -2.301 -0.057 -3.455 0 c -2.638 0.128 -5.124 -1.226 -6.444 -3.513 l -0.002 -0.002 c -1.951 -3.378 -6.269 -4.535 -9.645 -2.584 l -9.352 5.4 c -3.378 1.951 -4.535 6.269 -2.584 9.645 l 0.002 0.002 c 1.321 2.286 1.25 5.117 -0.18 7.336 c -0.625 0.972 -1.201 1.97 -1.726 2.993 c -1.209 2.353 -3.625 3.836 -6.269 3.836 H 7.063 c -3.9 0 -7.061 3.162 -7.061 7.061 v 10.801 c 0 3.9 3.162 7.061 7.061 7.061 l 0 0 c 2.685 0 5.093 1.545 6.327 3.929 c 0.245 0.475 0.504 0.948 0.774 1.416 c 0.27 0.468 0.55 0.928 0.84 1.378 c 1.448 2.26 1.582 5.117 0.239 7.443 c -1.951 3.378 -0.792 7.696 2.584 9.645 l 9.352 5.4 c 3.378 1.951 7.696 0.792 9.645 -2.584 l 0.002 -0.003 c 1.322 -2.291 3.815 -3.641 6.456 -3.512 c 1.149 0.056 2.301 0.057 3.455 0 c 2.638 -0.128 5.124 1.226 6.444 3.513 l 0.002 0.002 c 1.951 3.378 6.268 4.535 9.645 2.584 l 9.352 -5.4 c 3.378 -1.949 4.535 -6.268 2.584 -9.645 l -0.002 -0.002 c -1.321 -2.286 -1.25 -5.117 0.18 -7.336 c 0.625 -0.972 1.201 -1.97 1.726 -2.993 c 1.209 -2.353 3.625 -3.836 6.269 -3.836 h 0.003 c 3.9 0 7.061 -3.162 7.061 -7.061 V 39.599 C 90.001 35.7 86.84 32.538 82.94 32.538 z M 54.998 62.318 c -9.565 5.523 -21.796 2.245 -27.317 -7.32 c -5.523 -9.565 -2.245 -21.796 7.32 -27.317 s 21.796 -2.245 27.317 7.32 C 67.841 44.566 64.563 56.797 54.998 62.318 z"/></svg>';
 
+/* ── what a saved tile can be shown as ─────────────────────────────────
+   A layout keeps every tile it was given; the board shows the ones whose
+   module is installed and enabled and — for a tile added from a picker
+   entry — whose entry (or an alias of it) the module offers right now. The
+   rest keep their place and draw nothing, and appear the moment the
+   registry offers them again: a Service timer waits for PCO Plan, a
+   transcript for its channel. Never the module's default in their place —
+   a wall of "All timers" where five different timers were is worse than
+   five gaps that fill themselves in. */
+
+function tileIsOffered(tile) {
+  const man = registry.get(tile.module);
+  if (!man) return false;
+  const variant = String(tile.variant || '');
+  if (!variant) return true; // the plain module tile — the module says what that means
+  const entries = Array.isArray(man.tiles) ? man.tiles : [];
+  // No list at all is a module whose tiles() did not answer in time (the
+  // server falls back to the classic single entry): mount, and let it sort
+  // its own variant out rather than blank the board over a slow answer.
+  if (!entries.length) return true;
+  return entries.some((e) => String(e.id) === variant || (Array.isArray(e.aliases) && e.aliases.includes(variant)));
+}
+
+/** Show tiles that have become offered; fold away tiles that have stopped being. */
+function reconcileOfferedTiles() {
+  let changed = false;
+  for (const tile of tiles) {
+    const shown = tileEls.has(tile.id);
+    const offered = tileIsOffered(tile);
+    if (offered && !shown) {
+      buildTile(tile);
+      changed = true;
+    } else if (!offered && shown) {
+      unmountModule(tile);
+      tileEls.get(tile.id)?.el.remove();
+      tileEls.delete(tile.id);
+      changed = true;
+    }
+  }
+  if (changed) rebuildDividers();
+  scheduleOfferedRecheck();
+}
+
+/* A module's entry list can change without anyone saving admin config: PCO
+   Plan comes back and, a few seconds later, the timers module is offering
+   its timers again. No event marks that moment, so while any tile is folded
+   away the registry is re-read every few seconds until nothing is. It costs
+   one GET while something is hidden and nothing at all otherwise. */
+const OFFERED_RECHECK_MS = 6000;
+let offeredRecheck = 0;
+function scheduleOfferedRecheck() {
+  clearTimeout(offeredRecheck);
+  if (!tiles.some((t) => !tileEls.has(t.id))) return;
+  offeredRecheck = setTimeout(async () => {
+    offeredRecheck = 0;
+    if (await loadRegistry()) reconcileOfferedTiles();
+    else scheduleOfferedRecheck();
+  }, OFFERED_RECHECK_MS);
+}
+
+/** The tiles a layout holds that the board is not showing, by name. */
+function unshownTileNames() {
+  return tiles.filter((t) => !tileEls.has(t.id))
+    .map((t) => t.title || registry.get(t.module)?.name || t.module);
+}
+
 function buildTile(tile) {
   const man = registry.get(tile.module);
 
@@ -741,6 +975,7 @@ function rebuildDividers() {
   for (const L of tiles) {
     for (const R of tiles) {
       if (L === R || L.x + L.w !== R.x) continue;
+      if (!tileEls.has(L.id) || !tileEls.has(R.id)) continue;
       const top = Math.max(L.y, R.y);
       const bottom = Math.min(L.y + L.h, R.y + R.h);
       if (bottom <= top) continue;
@@ -858,10 +1093,14 @@ function addTile(moduleId, entry = null) {
     toast(`${entry.name} is already on this dashboard`);
     return;
   }
+  // Sizes are declared for the default twelve-column grid; scaled so a new
+  // tile lands at about the size its author meant, whatever the density here.
+  const scale = COLS / GRID_DEFAULT;
   const defaultSize = entry?.defaultSize || man?.defaultSize;
+  const floor = minSizeOf({ module: moduleId, minSize: entry?.minSize });
   const size = {
-    w: Math.max(1, Math.min(COLS, defaultSize?.w || 4)),
-    h: Math.max(1, defaultSize?.h || 3),
+    w: Math.max(floor.w, 1, Math.min(COLS, Math.round((defaultSize?.w || 4) * scale))),
+    h: Math.max(floor.h, 1, Math.round((defaultSize?.h || 3) * scale)),
   };
   const spot = findSpot(size.w, size.h);
   const settings = {};
@@ -1859,9 +2098,12 @@ function renderLayout(layout) {
   // "reset" can simply hand over no tiles.
   const list = Array.isArray(layout) ? layout : (layout?.tiles || []);
   clearAllTiles();
+  // Density first: the tiles are clamped and placed against it.
+  if (!Array.isArray(layout)) setGridCols(layout?.gridCols ?? GRID_DEFAULT, { save: false });
   tiles = list.map(sanitizeTile);
   if (!Array.isArray(layout)) setAutoHideHeads(Boolean(layout?.autoHideHeads), { save: false });
-  for (const tile of tiles) buildTile(tile);
+  for (const tile of tiles) if (tileIsOffered(tile)) buildTile(tile);
+  scheduleOfferedRecheck();
   refreshEmptyState();
   rebuildDividers();
   if (document.body.classList.contains('fullscreen')) applyFullscreenFit();
@@ -1924,6 +2166,13 @@ function renderAddMenu(menu) {
 wireDropdown('layout-btn', 'layout-menu', async (menu, stillOpen) => {
   menu.innerHTML = '';
 
+  // Density first: the one thing in here that is not a layout but the board
+  // the layouts are arranged on.
+  menu.appendChild(gridStepper());
+  const stepperDivider = document.createElement('div');
+  stepperDivider.className = 'menu-divider';
+  menu.appendChild(stepperDivider);
+
   menu.appendChild(menuItem('Save as named layout…', async () => {
     menu.hidden = true;
     if (!tiles.length) {
@@ -1937,14 +2186,31 @@ wireDropdown('layout-btn', 'layout-menu', async (menu, stillOpen) => {
     });
     if (!name) return;
     try {
+      // Saving over a name is asked about first — and the copy it replaces
+      // is kept one back on the server, so a yes is not the end of it either.
+      const existing = await fetch('/api/layouts')
+        .then((r) => (r.ok ? r.json() : { layouts: [] }))
+        .then((b) => (b.layouts || []).find((l) => l.name === name))
+        .catch(() => null);
+      if (existing) {
+        const when = existing.updated ? new Date(existing.updated).toLocaleString() : 'earlier';
+        const go = await confirmModal({
+          title: `Replace “${name}”?`,
+          body: `It was saved ${when} with ${existing.tiles} tile${existing.tiles === 1 ? '' : 's'}. The copy it replaces is kept as its previous version.`,
+          okLabel: 'Replace',
+        });
+        if (!go) return;
+      }
       const res = await fetch('/api/layouts/' + encodeURIComponent(name), {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ layout: { autoHideHeads, tiles } }),
+        body: JSON.stringify({ layout: { autoHideHeads, gridCols: COLS, tiles } }),
       });
       const body = await res.json().catch(() => ({}));
       if (!res.ok) throw new Error(body.error || 'Save failed (' + res.status + ')');
-      toast(`Saved “${name}” — any browser can load it now`);
+      toast(body.replaced
+        ? `Replaced “${name}” — the earlier copy is kept as its previous version`
+        : `Saved “${name}” — any browser can load it now`);
     } catch (e) {
       toast(e.message, true);
     }
@@ -1984,9 +2250,33 @@ wireDropdown('layout-btn', 'layout-menu', async (menu, stillOpen) => {
         if (!res.ok) throw new Error(body.error || 'Load failed (' + res.status + ')');
         // Loading copies the layout into this browser's own state — it
         // does not live-link browsers together.
+        let outgoing = null;
+        try { outgoing = localStorage.getItem(LS_LAYOUT); } catch { /* fine */ }
+        const gridBefore = COLS;
         renderLayout(body.layout);
         saveLayout();
-        toast(`Loaded “${l.name}”`);
+        try { if (outgoing) localStorage.setItem(LS_LAYOUT_PREVIOUS, outgoing); } catch { /* fine */ }
+        const unshown = unshownTileNames();
+        const count = `${tiles.length} tile${tiles.length === 1 ? '' : 's'}`;
+        const gridNote = COLS !== gridBefore ? ` on a ${COLS}-column grid` : '';
+        const note = unshown.length
+          ? `, ${unshown.length} not shown — ${unshown.join(', ')} ${unshown.length === 1 ? 'isn’t' : 'aren’t'} offered right now`
+          : '';
+        toast(`Loaded “${l.name}”: ${count}${gridNote}${note}`, false, {
+          ms: unshown.length ? 10000 : 7000,
+          action: outgoing ? {
+            label: 'Undo',
+            onClick() {
+              try {
+                renderLayout(JSON.parse(outgoing));
+                saveLayout();
+                toast('Back to the arrangement you had');
+              } catch {
+                toast('Could not go back', true);
+              }
+            },
+          } : null,
+        });
       } catch (e) {
         toast(e.message, true);
       }
@@ -2128,7 +2418,8 @@ function applyFullscreenFit() {
 }
 
 function clearFullscreenFit() {
-  grid.style.gridTemplateColumns = '';
+  // Back to this browser's density, not the stylesheet's twelve.
+  grid.style.gridTemplateColumns = `repeat(${COLS}, minmax(0, 1fr))`;
   grid.style.gridAutoRows = '';
   gridwrap.classList.remove('no-scroll');
   for (const tile of tiles) {
@@ -2188,7 +2479,7 @@ function subscribeEvents() {
   // Rides on the page's one stream connection (see sseSubscribe) as `shell:`.
   sseSubscribe('/api/events', {
     events: {
-      'modules-changed': () => handleModulesChanged(),
+      'modules-changed': () => handleModulesChanged().then(reconcileOfferedTiles),
       theme: handleThemeEvent,
     },
   });
@@ -2270,6 +2561,10 @@ async function boot() {
   }
   renderLayout(loadLayoutFromStorage());
   subscribeEvents();
+  // Entries a module builds at runtime (a timer per discovered source) can
+  // land a beat after the first registry read; look once more shortly after
+  // boot so a tile hidden only by that timing appears without a nudge.
+  setTimeout(async () => { if (await loadRegistry()) reconcileOfferedTiles(); }, 5000);
 }
 
 boot();

public/style.css

@@ -187,6 +187,36 @@ body.menu-hidden #topbar {
   white-space: normal;
 }
 .menu-divider { height: 1px; background: var(--border); margin: 5px 4px; }
+
+/* the Layouts menu's grid-density row: Grid Size  − 12 + */
+.menu-stepper {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px 8px;
+  font-size: 13px;
+}
+.menu-stepper-label { flex: 1; }
+.menu-stepper-btn {
+  width: 26px;
+  height: 26px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: 6px;
+  color: var(--text);
+  cursor: pointer;
+}
+.menu-stepper-btn:hover { border-color: var(--muted); }
+.menu-stepper-btn[disabled] { opacity: 0.35; cursor: default; }
+.menu-stepper-btn svg { width: 12px; height: 12px; display: block; }
+.menu-stepper-value {
+  min-width: 28px;
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+}
 .menu-title {
   padding: 6px 10px 3px;
   color: var(--muted);
@@ -906,6 +936,24 @@ body.fullscreen #grid { padding-bottom: 0; }
   transition: opacity 0.25s ease;
 }
 #toast[hidden] { display: none; }
+#toast button {
+  margin-left: 12px;
+  padding: 3px 10px;
+  border: 1px solid var(--accent);
+  border-radius: 5px;
+  background: none;
+  color: var(--accent);
+  font: inherit;
+  font-weight: 700;
+  cursor: pointer;
+}
+#toast button:hover { background: var(--accent); color: var(--accent-text); }
+#modal .modal-copy {
+  color: var(--muted);
+  font-size: 13px;
+  line-height: 1.5;
+  margin: 6px 0 14px;
+}
 #toast.error { border-color: var(--danger); }
 
 /* ── scrollbars ────────────────────────────────────────────────────── */

server.js

@@ -1601,13 +1601,53 @@ function layoutPath(name) {
   return path.join(LAYOUTS_DIR, name + '.json');
 }
 
-/** Keep only the fields a layout is made of; everything else is dropped. */
+/** The copy a save replaced — one back, kept until the next save replaces it.
+    Names cannot contain a dot (layoutNameOk), so this can never be a real
+    layout's own file. */
+function previousLayoutPath(name) {
+  return path.join(LAYOUTS_DIR, name + '.previous.json');
+}
+
+/* A saved layout is `{ v, autoHideHeads, tiles }`. The fields the shell knows
+   are checked for shape; anything else a tile carries rides along untouched.
+   That second part is the lesson of a bug: this function used to rebuild each
+   tile from the fields it knew and drop the rest, and for seventeen days it
+   dropped `variant` — every solo timer saved to a server came back as "All
+   timers". The server is the part of ProdDash that lags (a booth updates
+   weeks after the dev machine), so it must never be the one deciding which
+   tile fields exist. Retired fields are the one exception: they are dropped
+   so an old file does not haunt a new client. */
+
+const LAYOUT_VERSION = 2;
+const GRID_STEPS = [8, 10, 12, 16, 20, 24]; // the shell's grid densities
+const MAX_LAYOUT_TILES = 100;
+const KNOWN_TILE_FIELDS = new Set(['id', 'module', 'x', 'y', 'w', 'h', 'settings', 'variant', 'title', 'headPinned', 'minSize']);
+const RETIRED_TILE_FIELDS = new Set(['headHidden']);
+
+/** An unknown tile field is kept when it is a sane key holding small, plain JSON. */
+function keepUnknownTileField(key, value) {
+  if (!/^[A-Za-z][A-Za-z0-9_]{0,39}$/.test(key)) return false;
+  switch (typeof value) {
+    case 'string': return value.length <= 2000;
+    case 'number': return Number.isFinite(value);
+    case 'boolean': return true;
+    case 'object':
+      if (value === null) return false;
+      try { return JSON.stringify(value).length <= 20000; } catch { return false; }
+    default: return false;
+  }
+}
+
 function sanitizeLayout(raw) {
-  const tiles = Array.isArray(raw?.tiles) ? raw.tiles.slice(0, 100) : [];
+  const tiles = Array.isArray(raw?.tiles) ? raw.tiles : [];
   return {
+    v: LAYOUT_VERSION,
     // Whether tile title bars auto-hide is part of how a dashboard is
     // arranged, so it travels with the layout like the tiles themselves.
     autoHideHeads: Boolean(raw?.autoHideHeads),
+    // The grid density the layout was arranged on, when it says and it is one
+    // the shell knows; a browser loading it cuts its board the same way.
+    ...(GRID_STEPS.includes(Number(raw?.gridCols)) ? { gridCols: Number(raw.gridCols) } : {}),
     tiles: tiles.map((t) => {
       const tile = {
         id: String(t?.id || ''),
@@ -1618,8 +1658,6 @@ function sanitizeLayout(raw) {
         h: Number(t?.h) || 1,
         settings: t?.settings && typeof t.settings === 'object' ? t.settings : {},
         // Which picker entry the tile came from, and what it was called.
-        // Without these a saved "Now" tile comes back as the full Now/Next
-        // card, and a solo timer comes back with a full tile's settings.
         variant: String(t?.variant || ''),
         title: String(t?.title || ''),
         headPinned: Boolean(t?.headPinned),
@@ -1627,6 +1665,10 @@ function sanitizeLayout(raw) {
       if (Number(t?.minSize?.w) > 0 && Number(t?.minSize?.h) > 0) {
         tile.minSize = { w: Number(t.minSize.w), h: Number(t.minSize.h) };
       }
+      for (const [key, value] of Object.entries(t && typeof t === 'object' ? t : {})) {
+        if (KNOWN_TILE_FIELDS.has(key) || RETIRED_TILE_FIELDS.has(key)) continue;
+        if (keepUnknownTileField(key, value)) tile[key] = value;
+      }
       return tile;
     }),
   };
@@ -1640,17 +1682,23 @@ async function handleLayoutsApi(req, res, urlPath) {
     } catch { /* no layouts dir yet */ }
     const layouts = [];
     for (const file of files.sort()) {
+      if (file.endsWith('.previous.json')) continue; // a save's one-back copy, listed on its layout
       const name = file.slice(0, -5);
       const data = readJson(path.join(LAYOUTS_DIR, file), null);
       if (!data) continue;
       let updated = null;
       try { updated = fs.statSync(path.join(LAYOUTS_DIR, file)).mtime.toISOString(); } catch { /* fine */ }
-      layouts.push({ name, tiles: Array.isArray(data.tiles) ? data.tiles.length : 0, updated });
+      layouts.push({
+        name,
+        tiles: Array.isArray(data.tiles) ? data.tiles.length : 0,
+        updated,
+        hasPrevious: fs.existsSync(previousLayoutPath(name)),
+      });
     }
     return sendJson(res, 200, { layouts });
   }
 
-  const m = urlPath.match(/^\/api\/layouts\/([^/]+)(\/rename)?$/);
+  const m = urlPath.match(/^\/api\/layouts\/([^/]+)(\/rename|\/restore)?$/);
   if (!m) return sendJson(res, 404, { error: 'Unknown endpoint.' });
   let name;
   try {
@@ -1683,12 +1731,20 @@ async function handleLayoutsApi(req, res, urlPath) {
     }
     const layout = sanitizeLayout(body.layout);
     if (!layout.tiles.length) return sendJson(res, 400, { error: 'Refusing to save an empty layout.' });
+    if (layout.tiles.length > MAX_LAYOUT_TILES) {
+      // Saying no beats quietly saving the first hundred and losing the rest.
+      return sendJson(res, 400, { error: `A layout can hold ${MAX_LAYOUT_TILES} tiles; this one has ${layout.tiles.length}.` });
+    }
+    const replaced = fs.existsSync(layoutPath(name));
     try {
+      // The copy being replaced is kept one back, so a save over the wrong
+      // name is a restore away rather than gone.
+      if (replaced) fs.copyFileSync(layoutPath(name), previousLayoutPath(name));
       writeJson(layoutPath(name), layout);
     } catch (err) {
       return sendJson(res, 500, { error: `Could not save ${layoutPath(name)}: ${err?.message || err}` });
     }
-    return sendJson(res, 200, { ok: true, name });
+    return sendJson(res, 200, { ok: true, name, replaced });
   }
 
   if (!m[2] && req.method === 'DELETE') {
@@ -1698,10 +1754,11 @@ async function handleLayoutsApi(req, res, urlPath) {
     } catch {
       return sendJson(res, 404, { error: `No layout named "${name}".` });
     }
+    fs.rmSync(previousLayoutPath(name), { force: true });
     return sendJson(res, 200, { ok: true });
   }
 
-  if (m[2] && req.method === 'POST') {
+  if (m[2] === '/rename' && req.method === 'POST') {
     if (refuseAdminWrite(req, res)) return;
     let body = {};
     try {
@@ -1725,6 +1782,25 @@ async function handleLayoutsApi(req, res, urlPath) {
     return sendJson(res, 200, { ok: true, name: next });
   }
 
+  // Put back the copy the last save replaced. The two swap, so a restore is
+  // itself one restore away from being undone.
+  if (m[2] === '/restore' && req.method === 'POST') {
+    if (refuseAdminWrite(req, res)) return;
+    const current = layoutPath(name);
+    const previous = previousLayoutPath(name);
+    if (!fs.existsSync(previous)) return sendJson(res, 404, { error: `"${name}" has no previous version to go back to.` });
+    try {
+      const swapTmp = current + '.swap';
+      const hadCurrent = fs.existsSync(current);
+      if (hadCurrent) fs.renameSync(current, swapTmp);
+      fs.renameSync(previous, current);
+      if (hadCurrent) fs.renameSync(swapTmp, previous);
+    } catch (err) {
+      return sendJson(res, 500, { error: 'Restore failed: ' + (err?.message || err) });
+    }
+    return sendJson(res, 200, { ok: true, name });
+  }
+
   sendJson(res, 405, { error: 'Method not allowed.' });
 }
 

tools/layout-roundtrip.test.js

@@ -0,0 +1,159 @@
+'use strict';
+
+/**
+ * Round-trips a layout through the server's layouts API and checks that
+ * nothing is lost on the way: a fully-populated tile, a tile field the server
+ * has never heard of, the one-back copy a save leaves behind, restore, the
+ * tile cap and delete.
+ *
+ *   node tools/layout-roundtrip.test.js
+ *
+ * Plain Node, no dependencies. Starts server.js on a spare port with a
+ * temporary data directory, talks to it over HTTP, exits non-zero on the
+ * first failure and always stops the server it started.
+ *
+ * It exists because of one bug: for seventeen days the server rebuilt each
+ * saved tile from the fields it knew and dropped the rest — including
+ * `variant`, so every solo timer saved to a booth came back as "All timers".
+ * A field added on the client must survive a server that has not heard of
+ * it, and this is where that is checked.
+ */
+
+const assert = require('node:assert/strict');
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+
+const ROOT = path.join(__dirname, '..');
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const probe = net.createServer();
+    probe.listen(0, '127.0.0.1', () => {
+      const { port } = probe.address();
+      probe.close(() => resolve(port));
+    });
+    probe.on('error', reject);
+  });
+}
+
+async function waitFor(url, ms = 15000) {
+  const deadline = Date.now() + ms;
+  let last = '';
+  while (Date.now() < deadline) {
+    try {
+      const r = await fetch(url);
+      if (r.ok) return;
+      last = 'HTTP ' + r.status;
+    } catch (err) {
+      last = err.message;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  throw new Error('server did not come up: ' + last);
+}
+
+(async () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proddash-layout-test-'));
+  const port = await freePort();
+  const child = spawn(process.execPath, ['server.js'], {
+    cwd: ROOT,
+    env: { ...process.env, PRODDASH_DATA_DIR: dataDir, PORT: String(port), PRODDASH_NO_REMOTE_CHECK: '1', PRODDASH_LAUNCHER: '1' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let log = '';
+  child.stdout.on('data', (d) => { log += d; });
+  child.stderr.on('data', (d) => { log += d; });
+
+  const base = `http://127.0.0.1:${port}`;
+  const api = async (p, init = {}) => {
+    const r = await fetch(base + p, { headers: { 'Content-Type': 'application/json' }, ...init });
+    return { status: r.status, body: await r.json().catch(() => ({})) };
+  };
+  const layoutsDir = path.join(dataDir, 'layouts');
+  let failed = false;
+
+  try {
+    await waitFor(base + '/api/theme');
+
+    // Every field the shell writes today, one it will write tomorrow, and one
+    // it has stopped writing.
+    const tile = {
+      id: 't1', module: 'propresenter-timers', x: 4, y: 2, w: 3, h: 2,
+      settings: { showNames: false, __tint: '#112233' },
+      variant: 'solo:pco-plan:service', title: 'Service', headPinned: true, minSize: { w: 2, h: 1 },
+      futureField: 'kept', futureFlag: true, futureBox: { a: 1 },
+      headHidden: true,
+    };
+
+    let r = await api('/api/layouts/Booth%20A', { method: 'PUT', body: JSON.stringify({ layout: { autoHideHeads: true, gridCols: 16, tiles: [tile] } }) });
+    assert.equal(r.status, 200, 'save: ' + JSON.stringify(r.body));
+    assert.equal(r.body.replaced, false, 'a first save replaces nothing');
+
+    r = await api('/api/layouts/Booth%20A');
+    assert.equal(r.status, 200);
+    const got = r.body.layout;
+    assert.equal(got.v, 2, 'the file carries a schema version');
+    assert.equal(got.autoHideHeads, true);
+    assert.equal(got.gridCols, 16, 'grid density travels with the layout');
+    const t = got.tiles[0];
+    for (const k of ['id', 'module', 'x', 'y', 'w', 'h', 'variant', 'title', 'headPinned']) assert.deepEqual(t[k], tile[k], k);
+    assert.deepEqual(t.settings, tile.settings, 'settings');
+    assert.deepEqual(t.minSize, tile.minSize, 'minSize');
+    assert.equal(t.futureField, 'kept', 'an unknown string field survives');
+    assert.equal(t.futureFlag, true, 'an unknown boolean survives');
+    assert.deepEqual(t.futureBox, { a: 1 }, 'an unknown object survives');
+    assert.equal('headHidden' in t, false, 'a retired field is dropped');
+
+    // Saving over the name keeps the copy it replaced.
+    r = await api('/api/layouts/Booth%20A', { method: 'PUT', body: JSON.stringify({ layout: { gridCols: 13, tiles: [{ ...tile, title: 'Service v2' }] } }) });
+    assert.equal(r.status, 200);
+    assert.equal(r.body.replaced, true, 'the second save reports a replacement');
+    assert.ok(fs.existsSync(path.join(layoutsDir, 'Booth A.previous.json')), 'the replaced copy is kept');
+    r = await api('/api/layouts');
+    assert.deepEqual(r.body.layouts.map((l) => [l.name, l.hasPrevious]), [['Booth A', true]],
+      'the listing shows one layout with a previous copy — not two layouts');
+
+    // Restore swaps them, so a second restore undoes the first. Admin is open
+    // here (no PIN), which is what a fresh data directory gives.
+    r = await api('/api/layouts/Booth%20A/restore', { method: 'POST', body: '{}' });
+    assert.equal(r.status, 200, 'restore: ' + JSON.stringify(r.body));
+    r = await api('/api/layouts/Booth%20A');
+    assert.equal(r.body.layout.tiles[0].title, 'Service', 'restore brings the earlier save back');
+    r = await api('/api/layouts/Booth%20A/restore', { method: 'POST', body: '{}' });
+    assert.equal(r.status, 200);
+    r = await api('/api/layouts/Booth%20A');
+    assert.equal(r.body.layout.tiles[0].title, 'Service v2', 'restoring again goes forward again');
+    assert.equal('gridCols' in r.body.layout, false, 'a density the shell does not offer is dropped, not stored');
+    r = await api('/api/layouts/Never%20Saved/restore', { method: 'POST', body: '{}' });
+    assert.equal(r.status, 404, 'nothing to restore is said, not faked');
+
+    // Too many tiles is refused, not trimmed.
+    const many = Array.from({ length: 101 }, (_, i) => ({ ...tile, id: 't' + i }));
+    r = await api('/api/layouts/Too%20Big', { method: 'PUT', body: JSON.stringify({ layout: { tiles: many } }) });
+    assert.equal(r.status, 400);
+    assert.match(String(r.body.error || ''), /100 tiles/, 'the refusal names the cap');
+    assert.equal(fs.existsSync(path.join(layoutsDir, 'Too Big.json')), false, 'nothing was written');
+
+    // Delete takes the previous copy with it.
+    r = await api('/api/layouts/Booth%20A', { method: 'DELETE' });
+    assert.equal(r.status, 200);
+    assert.equal(fs.existsSync(path.join(layoutsDir, 'Booth A.json')), false);
+    assert.equal(fs.existsSync(path.join(layoutsDir, 'Booth A.previous.json')), false, 'the previous copy is gone too');
+    r = await api('/api/layouts');
+    assert.deepEqual(r.body.layouts, [], 'nothing left listed');
+
+    console.log('layout round-trip: every check passed');
+  } catch (err) {
+    failed = true;
+    console.error('FAIL:', err.message);
+    console.error('--- last of the server log ---\n' + log.slice(-2000));
+  } finally {
+    child.kill('SIGTERM');
+    await new Promise((r) => setTimeout(r, 400));
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+  process.exit(failed ? 1 : 0);
+})();

tools/pco-band-mock.js

@@ -0,0 +1,49 @@
+// Minimal Planning Center mock for the Band Lineup module: service types, one
+// plan today, its team_members (with person+team includes), People birthdates,
+// and avatar bytes. Enough to exercise the whole board build.
+const http = require('http');
+const PORT = Number(process.argv[2] || 24710);
+const JPEG = Buffer.from('/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////wAALCAABAAEBAREA/8QAFAABAAAAAAAAAAAAAAAAAAAAAP/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AfwD/2Q==', 'base64');
+const TODAY = new Date();
+const iso = (d) => d.toISOString();
+// One person's birthday lands in this Wed–Tue week (today is a Wed in the test).
+const inWeek = new Date(TODAY.getFullYear(), TODAY.getMonth(), TODAY.getDate() + 2);
+const bdayInWeek = `1994-${String(inWeek.getMonth()+1).padStart(2,'0')}-${String(inWeek.getDate()).padStart(2,'0')}`;
+
+const PEOPLE = {
+  p1: { name: 'Lemuel Maldonado', pos: 'Vox 1', team: 'Vocals', bd: '1990-03-04' },
+  p2: { name: 'Wes Carter',       pos: 'Vox 2', team: 'Vocals', bd: null },
+  p3: { name: 'Jessica Proulx',   pos: 'Vox 3', team: 'Vocals', bd: '1992-11-01' },
+  p4: { name: 'Jeremy Cruz',      pos: 'Guitar / Lead', team: 'Band', bd: null },
+  p5: { name: 'Alex Gaitan',      pos: 'Drums', team: 'Band', bd: bdayInWeek }, // celebrating
+  p6: { name: 'Rosaliz Gomez',    pos: 'Piano', team: 'Band', bd: null },
+  p7: { name: 'George Acosta',    pos: 'MC', team: 'Production', bd: null },
+  p8: { name: 'Not Shown',        pos: 'Camera 2', team: 'Video', bd: null }, // team not allowed → filtered out
+};
+const TEAMS = { Vocals: 't1', Band: 't2', Production: 't3', Video: 't4' };
+
+function send(res, obj) { res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(obj)); }
+
+const server = http.createServer((req, res) => {
+  const u = new URL(req.url, 'http://x'); const p = u.pathname;
+  if (p.startsWith('/avatar/')) { res.writeHead(200, { 'Content-Type': 'image/jpeg' }); return res.end(JPEG); }
+  if (p === '/services/v2/folders') return send(res, { data: [] });
+  if (p === '/services/v2/service_types') return send(res, { data: [{ id: '1', type: 'ServiceType', attributes: { name: 'Sunday Service' }, relationships: { parent: { data: null } } }] });
+  if (/^\/services\/v2\/service_types\/1\/plans$/.test(p)) {
+    if (u.searchParams.get('filter') === 'past') return send(res, { data: [] });
+    return send(res, { data: [{ id: '100', type: 'Plan', attributes: { sort_date: iso(TODAY), title: 'Taking Thoughts Captive - Part 4', dates: 'September 20, 2026' } }] });
+  }
+  if (/^\/services\/v2\/service_types\/1\/plans\/100\/team_members$/.test(p)) {
+    const data = []; const included = [];
+    for (const [id, v] of Object.entries(PEOPLE)) {
+      data.push({ id: `tm-${id}`, type: 'PlanPerson', attributes: { status: 'C', team_position_name: v.pos }, relationships: { person: { data: { type: 'Person', id } }, team: { data: { type: 'Team', id: TEAMS[v.team] } } } });
+      included.push({ id, type: 'Person', attributes: { full_name: v.name, photo_url: `http://127.0.0.1:${PORT}/avatar/${id}` } });
+    }
+    for (const [name, id] of Object.entries(TEAMS)) included.push({ id, type: 'Team', attributes: { name } });
+    return send(res, { data, included, links: {} });
+  }
+  const person = p.match(/^\/people\/v2\/people\/([^/]+)$/);
+  if (person) { const v = PEOPLE[person[1]]; return send(res, { data: { id: person[1], type: 'Person', attributes: { birthdate: v ? v.bd : null } } }); }
+  res.writeHead(404); res.end('{}');
+});
+server.listen(PORT, '127.0.0.1', () => console.log(`[pco-band-mock] on http://127.0.0.1:${PORT}`));