Merge pull request 'Band Lineup 1.13.0: a photo per instrument, your own photos win, spots stay in reach while dragging' (#53) from claude/band-lineup-photos into main

DJ plays drums one week and sings the next; one photo can't fit both. A
person can now have a photo per instrument, named "Name - Instrument"
("DJ - Drums.jpg", "DJ - Vocals.jpg"), plus a plain "DJ.jpg" for
everything else. Sync reads the instrument family of the spot each person
lands in (its bracketed role, else their PCO position) and picks:

1. the photo picked by hand for them on that instrument;
2. a photo named for that instrument;
3. their everyday pick, else their best-named photo. A photo of them on
   another instrument still beats PCO's headshot.

Families keep the shorthands together: Vox/Vocals/Singer, Keys/Piano/Pad,
Drums/Perc, Bass, Guitar/Electric/Acoustic/Rhythm, Leader. A photo
dropped onto someone is remembered per person per instrument
("<id>|drums"), so a drum pick never overrides the vocal photo. A spot
naming several roles files under its most specific: Leader, then Vocals,
Drums, Keys, Bass, Guitar. Photo names from files now collapse the spaces
left by "Name - Instrument".

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

CLAUDE.md

@@ -52,6 +52,7 @@ title-bar controls). The rules that matter most:
   `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`).
   `node tools/ableset-mock.js 39071` (AbleSet over OSC/UDP; point the AbleSet module at `127.0.0.1:39071`; `--stopped`, `--no-live`, `--speed 4`).
+  `node tools/vista-midi-mock.js 5104` (a network MIDI / RTP-MIDI session for Vista Cues; point its first sender at `127.0.0.1:5104` and paste the cue sheet it prints; `--invite 127.0.0.1:5040` joins from its side, `--name`, `--channel`, `--every`, `--notes 2,23,8`).
 
 ## Reference code (read-only forks — don't develop these here)
 

README.md

@@ -521,11 +521,28 @@ below. Nothing is installed without someone clicking.
   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
+  title bar opens that library — the spots pinned on top, the photos (with a
-  to swap, rename or clear. Planning Center is optional auto-fill on top, not
+  name search) scrolling below — drag a photo onto a slot (mouse, or press and
-  the source of truth: **Sync** reads the upcoming plan's team members and
+  hold on a touchscreen), drag between slots to swap, rename or clear.
-  drops each into the slot matching their position, filling only slots nobody
+  Dropping a photo onto the person already in a spot makes it *their* photo
-  placed by hand, so a guest pinned on Thursday survives Sunday's sync.
+  for that instrument (a nickname like "Rose" for Rosaliz counts): they keep
+  their Planning Center name and spot, and every later Sync uses it whenever
+  they are on that instrument.
+  Planning Center is optional auto-fill on top, not the source of truth:
+  **Sync** reads the upcoming plan's team members and places each one. A
+  person whose Planning Center note names their mic ("Mix 8, VOX 5") goes to
+  that slot — this is how the leader and vocalists, whose position is just
+  "Vocalist", land on the right mic — and everyone else goes to the slot
+  matching their position, one slot per person. Photos come from the library
+  whenever it has one of them, and Planning Center's headshot only when it
+  has none. Someone who plays more than one thing can have a photo per
+  instrument, named `Name - Instrument` (`DJ - Drums.jpg`, `DJ - Vocals.jpg`;
+  Vox/Vocals, Keys/Piano, Drums, Bass, Guitar/Electric/Acoustic, Leader), and
+  a plain `DJ.jpg` for everything else: Sync uses the one for the spot they
+  are in that week. A photo dropped onto someone is remembered for that
+  instrument only. Anything placed or moved by
+  hand for that plan stays put through later syncs; last week's people are
+  replaced.
   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
@@ -550,6 +567,36 @@ below. Nothing is installed without someone clicking.
   soon as it does) and **Marks** (how long a mark lives).
   Tile settings: campuses, card or list layout, and a **Show** group for the
   day, role, resi source, campuses fed, notes and the updated line.
+- **Vista Cues** — which Vista 3 cue lists are live, for a booth where
+  nobody runs lighting and ProPresenter and the tracks rig fire Vista's cue
+  lists over network MIDI. Vista sends no feedback of any kind (its OSC only
+  takes commands), so the module listens instead: it joins the senders'
+  network MIDI sessions as one more participant, the way Vista does, hears
+  every note Vista hears, and turns each one into "Go on Walk-in", "Release
+  Worship 1"… from the cue sheet pasted into admin. The tile shows the list
+  fired last, large, with how long ago and who fired it; the other lists
+  still live; the recent notes; and which senders are connected. What it
+  shows is what Vista was *told*: if Vista is closed or someone works the
+  desk by hand, the two can differ, and the title bar's eraser forgets every
+  live list. Plain JavaScript (RTP-MIDI over UDP), no helper; on macOS it
+  advertises itself over Bonjour so it shows up in Audio MIDI Setup's
+  Directory. Admin config: up to three senders (a name, and the host and
+  port of each machine's network session — ProPresenter, the tracks rig,
+  Companion; ProdDash keeps inviting itself in, so each session's "Who may
+  connect to me" must be Anyone, or connect from the sender's Directory
+  instead), the cue sheet (one line per note: `0 = Pre Service`,
+  `61 release Walk-in`, `127 release all`, `30 flash Blinder Flash 1` for a
+  momentary hit, also pause, back, note names, a channel, program changes),
+  middle C naming, whether a Go releases the others, and a folded **This
+  machine** group for the session name, port (UDP 5040 and 5041) and
+  Bonjour. A sheet with no release notes uses groups: a line `[Color]`
+  starts one, a Go in a group replaces that group's live list, and the
+  first group is the tile's headline — so the tile reads "Message" with
+  Color · Blue and House · House Lights Message beside it. A Go in that
+  first group (the main scene) takes over the look and clears the rest, as
+  Vista's last-takes-precedence does; FX fired after it layer on again
+  (the **Main group takes over** switch). Tile settings: other lists,
+  recent, senders, unmapped notes — text size is − / + in the title bar.
 - **Clock** — a big booth clock; also the smallest possible module and the
   reference for module authors.
 
@@ -565,7 +612,10 @@ timers + timecode on `127.0.0.1:1600`), `node tools/pco-mock.js`
 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
+`BAND_LINEUP_API_BASE=http://127.0.0.1:24710`) and
+`node tools/vista-midi-mock.js 5104` (a network MIDI session playing a cue
+sheet's notes, as ProPresenter does for Vista — point Vista Cues' first
+sender at `127.0.0.1:5104` and paste the sheet it prints). See the testing section of
 the [module guide](docs/MODULE-GUIDE.md).
 
 ## Install as a desktop web app

modules/band-lineup/client.js

@@ -1,5 +1,5 @@
 // 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)
+// The Edit button opens an editor: an uploaded-photo library you drag (or tap)
 // 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.
@@ -14,26 +14,108 @@ export default function create({ root, moduleApi }) {
   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).
+  /* ---------- drag (pointer events: one path for mouse, pen and touch) ----------
-  let dragScrolling = false;
+   * Native HTML drag-and-drop never fires for a finger, drops onto a card's child elements
-  let dragY = 0;
+   * flicker, and a board update arriving mid-drag rebuilt the editor out from under it. This
-  let dragBody = null;
+   * drives the drag by hand instead: a mouse drags as soon as it moves; a finger holds still for
-  let dragRaf = null;
+   * a moment first (so a quick swipe still scrolls the editor). A floating copy of the photo
-  function startDragAutoScroll() {
+   * follows the pointer, the spot under it lights up, and the editor auto-scrolls near its
-    if (dragRaf) return;
+   * edges. Board updates that arrive during a drag wait until it ends. */
-    const tick = () => {
+  const DRAG_MOVE_PX = 6;
-      if (!dragScrolling || !dragBody || !dragBody.isConnected) { dragRaf = null; return; }
+  const TOUCH_HOLD_MS = 220;
-      const r = dragBody.getBoundingClientRect();
+  let drag = null;          // { kind: 'lib'|'slot', id, body, ghost, over, x, y, raf }
-      const zone = 90; // generous edge band so you don't have to be pixel-accurate
+  let pending = null;       // a pointerdown that may become a drag
-      let dy = 0;
+  let renderHeld = false;   // a state update arrived mid-drag; render when it ends
-      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;
+  function slotUnder(x, y) {
-      if (dy) dragBody.scrollTop += dy;
+    const hit = document.elementFromPoint(x, y);
-      dragRaf = requestAnimationFrame(tick);
+    const cell = hit && hit.closest ? hit.closest('.bl-edit-slot') : null;
-    };
+    return cell && root.contains(cell) ? cell : null;
-    dragRaf = requestAnimationFrame(tick);
   }
-  function stopDragAutoScroll() { dragScrolling = false; if (dragRaf) { cancelAnimationFrame(dragRaf); dragRaf = null; } }
+  function beginDrag(p) {
+    const ghost = el('div', 'bl-drag-ghost');
+    ghost.dataset.module = 'band-lineup'; // lives on <body> (above every tile), so it carries its own scope
+    const src = p.source.querySelector('img');
+    if (src) { const img = document.createElement('img'); img.src = src.src; img.alt = ''; ghost.appendChild(img); }
+    else ghost.textContent = p.label || '';
+    document.body.appendChild(ghost);
+    drag = { kind: p.kind, id: p.id, body: p.body, ghost, over: null, x: p.x, y: p.y, raf: null, source: p.source };
+    p.source.classList.add('bl-dragging');
+    root.classList.add('bl-is-dragging');
+    moveDrag(p.x, p.y);
+    const tick = () => {
+      if (!drag) return;
+      // Auto-scroll whichever pane (spots or photos) the pointer is near the edge of.
+      const b = [...root.querySelectorAll('.bl-pane')].find((pane) => { const r = pane.getBoundingClientRect(); return drag.x >= r.left && drag.x <= r.right && drag.y >= r.top && drag.y <= r.bottom; });
+      if (b && b.scrollHeight > b.clientHeight) {
+        const r = b.getBoundingClientRect(); const zone = Math.min(60, r.height / 4); let dy = 0;
+        if (drag.y < r.top + zone) dy = -Math.ceil((r.top + zone - drag.y) / 4) - 2;
+        else if (drag.y > r.bottom - zone) dy = Math.ceil((drag.y - (r.bottom - zone)) / 4) + 2;
+        if (dy) { b.scrollTop += dy; moveDrag(drag.x, drag.y); }
+      }
+      drag.raf = requestAnimationFrame(tick);
+    };
+    drag.raf = requestAnimationFrame(tick);
+  }
+  function moveDrag(x, y) {
+    drag.x = x; drag.y = y;
+    drag.ghost.style.transform = `translate(${x}px, ${y}px)`;
+    const cell = slotUnder(x, y);
+    if (cell !== drag.over) {
+      if (drag.over) drag.over.classList.remove('bl-drop-over');
+      drag.over = cell;
+      if (cell) cell.classList.add('bl-drop-over');
+    }
+  }
+  function endDrag(drop) {
+    const d = drag; drag = null;
+    if (!d) return;
+    if (d.raf) cancelAnimationFrame(d.raf);
+    d.ghost.remove();
+    d.source.classList.remove('bl-dragging');
+    root.classList.remove('bl-is-dragging');
+    if (d.over) d.over.classList.remove('bl-drop-over');
+    if (drop && d.over) {
+      const to = d.over.dataset.index;
+      if (d.kind === 'lib') assign(to, d.id);
+      else if (d.id !== to) api(`/move?from=${d.id}&to=${to}`, { method: 'POST' });
+    }
+    if (renderHeld) { renderHeld = false; render(); }
+  }
+  function cancelPending() { if (pending && pending.timer) clearTimeout(pending.timer); pending = null; }
+  // Make `node` draggable. `kind`/`id` say what is being dragged.
+  function makeDraggable(node, kind, id, body, label) {
+    node.addEventListener('pointerdown', (e) => {
+      if (e.button !== 0 || drag) return;
+      if (e.target.closest('button')) return; // name / clear / delete buttons keep working
+      cancelPending();
+      pending = { kind, id, body, label, source: node, x: e.clientX, y: e.clientY, sx: e.clientX, sy: e.clientY, pointerId: e.pointerId, touch: e.pointerType !== 'mouse', armed: e.pointerType === 'mouse', timer: null };
+      if (pending.touch) {
+        const p = pending;
+        p.timer = setTimeout(() => { if (pending === p) { p.armed = true; beginDrag(p); try { node.setPointerCapture(p.pointerId); } catch { /* gone */ } } }, TOUCH_HOLD_MS);
+      }
+    });
+  }
+  // Document-level move/up so the drag survives leaving the card it started on.
+  function onPointerMove(e) {
+    if (drag) { e.preventDefault(); moveDrag(e.clientX, e.clientY); return; }
+    if (!pending || e.pointerId !== pending.pointerId) return;
+    const dist = Math.hypot(e.clientX - pending.sx, e.clientY - pending.sy);
+    if (pending.touch) { if (dist > 10) cancelPending(); return; } // moved before the hold: it's a scroll
+    if (dist >= DRAG_MOVE_PX) { const p = pending; pending = null; p.x = e.clientX; p.y = e.clientY; beginDrag(p); }
+  }
+  function onPointerUp(e) {
+    if (drag) { e.preventDefault(); suppressClick = true; setTimeout(() => { suppressClick = false; }, 0); endDrag(e.type === 'pointerup'); }
+    cancelPending();
+  }
+  let suppressClick = false; // the click that follows a drop must not also select / place
+  // While a finger drag is live, stop the page from scrolling under it.
+  function onTouchMove(e) { if (drag) e.preventDefault(); }
+  document.addEventListener('pointermove', onPointerMove, { passive: false });
+  document.addEventListener('pointerup', onPointerUp);
+  document.addEventListener('pointercancel', onPointerUp);
+  document.addEventListener('touchmove', onTouchMove, { passive: false });
+  function stopDragAutoScroll() { cancelPending(); endDrag(false); }
 
   /* ---------- confetti (always animates) ---------- */
   function makeParticle(w, h, intensity, seedY) {
@@ -79,11 +161,12 @@ export default function create({ root, moduleApi }) {
   function stopConfetti() { canvases.clear(); if (raf) { cancelAnimationFrame(raf); raf = null; } }
 
   function render() {
+    if (drag) { renderHeld = true; return; }
     stopConfetti();
     stopParallax();
-    root.innerHTML = '';
     if (choirBtn) choirBtn.classList.toggle('active', !!(state && state.choir));
-    if (editing) { renderEditor(); return; }
+    if (editing) { renderEditor(); return; } // replaces its own content, after noting scroll + focus
+    root.innerHTML = '';
 
     const board = el('div', 'bl-board');
     if (!state) { board.classList.add('bl-message'); board.textContent = 'Connecting…'; root.appendChild(board); return; }
@@ -158,13 +241,16 @@ export default function create({ root, moduleApi }) {
   }
 
   /* ---------- editor ---------- */
+  let libFilter = ''; // the photo search box, kept across re-renders
   function renderEditor() {
-    // No top bar: the photo source is managed in Admin (Google Drive link). Edit mode is just the
+    // No top bar: the photo source is managed in Admin (Google Drive link). Edit mode is two panes
-    // board on top and the picture picker (library) below it.
+    // that scroll on their own: the spots pinned on top, the photos below — so a photo found far
+    // down the list never has to be carried back up to its spot. Both panes keep their scroll
+    // position (and the search box its focus) when a board update redraws the editor.
+    const prevBoard = root.querySelector('.bl-board-pane'); const prevLib = root.querySelector('.bl-lib-pane');
+    const keep = { board: prevBoard ? prevBoard.scrollTop : 0, lib: prevLib ? prevLib.scrollTop : 0, searchFocused: document.activeElement && document.activeElement.classList && document.activeElement.classList.contains('bl-lib-search') };
     const wrap = el('div', 'bl-editor bl-editor-nobar');
-    const body = el('div', 'bl-editor-body');
+    const body = el('div', 'bl-editor-body bl-editor-split');
-    // 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');
@@ -176,14 +262,7 @@ export default function create({ root, moduleApi }) {
       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) {
+      if (slot.person) makeDraggable(cell, 'slot', String(slot.index), body, slot.person.name);
-        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 : ''));
@@ -191,26 +270,23 @@ export default function create({ root, moduleApi }) {
       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('click', (e) => { if (suppressClick) return; if (e.target.closest('.bl-edit-name') || e.target.closest('.bl-edit-clear')) return; if (selectedLibId) assign(slot.index, selectedLibId); });
-      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);
+    const boardPane = el('div', 'bl-pane bl-board-pane');
+    boardPane.appendChild(boardEl);
+    body.appendChild(boardPane);
 
-    // Library
+    // Library, with a name search
+    const libPane = el('div', 'bl-pane bl-lib-pane');
+    const search = el('input', 'bl-lib-search');
+    search.type = 'search'; search.placeholder = 'Find a photo…'; search.value = libFilter;
+    libPane.appendChild(search);
     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;
+      const item = el('div', 'bl-lib-item'); 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…');
@@ -219,19 +295,27 @@ export default function create({ root, moduleApi }) {
       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) => {
+      makeDraggable(item, 'lib', person.id, body, person.name);
-        e.dataTransfer.setData('text/plain', 'lib:' + person.id); e.dataTransfer.effectAllowed = 'copy';
+      item.addEventListener('click', () => { if (suppressClick) return; selectedLibId = selectedLibId === person.id ? '' : person.id; renderEditor(); });
-        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);
+    const applyFilter = () => {
+      const q = libFilter.trim().toLowerCase();
+      for (const item of lib.querySelectorAll('.bl-lib-item')) {
+        const nm = item.querySelector('.bl-lib-name');
+        item.style.display = !q || (nm && nm.textContent.toLowerCase().includes(q)) ? '' : 'none';
+      }
+    };
+    search.addEventListener('input', () => { libFilter = search.value; applyFilter(); });
+    applyFilter();
+    libPane.appendChild(lib);
+    body.appendChild(libPane);
     wrap.appendChild(body);
 
     root.innerHTML = '';
     root.appendChild(wrap);
+    boardPane.scrollTop = keep.board; libPane.scrollTop = keep.lib;
+    if (keep.searchFocused) { search.focus(); try { search.setSelectionRange(search.value.length, search.value.length); } catch { /* type=search */ } }
   }
 
   function assign(slotIndex, personId) {
@@ -260,7 +344,7 @@ export default function create({ root, moduleApi }) {
         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(); } });
+      const editBtn = moduleApi.header.addButton({ icon: EDIT_ICON, title: 'Edit board', onClick() { editing = !editing; if (editing) libFilter = ''; 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>';
@@ -293,6 +377,10 @@ export default function create({ root, moduleApi }) {
       stopConfetti();
       stopParallax();
       stopDragAutoScroll();
+      document.removeEventListener('pointermove', onPointerMove);
+      document.removeEventListener('pointerup', onPointerUp);
+      document.removeEventListener('pointercancel', onPointerUp);
+      document.removeEventListener('touchmove', onTouchMove);
       root.innerHTML = '';
     },
   };

modules/band-lineup/matching.js

@@ -117,9 +117,61 @@ function scoreMatch(slotLabel, positionLabel) {
  * member or null. `MIN_SCORE` keeps a weak coincidence from claiming a slot.
  */
 const MIN_SCORE = 60;
+
+/** The mix numbers a label names ("[VOX 5] MIX 8" → {"8"}; "Mix 8, VOX 5" → {"8"}). */
+function mixNumbers(value) {
+  const out = new Set(); const re = /\bmix\s*(\d+)\b/gi; let m;
+  while ((m = re.exec(String(value || '')))) out.add(m[1]);
+  return out;
+}
+
+/**
+ * How well a person's Planning Center note names a spot. The booth writes the mic/role into each
+ * vocalist's and the leader's note every week ("Mix 8, VOX 5", "DP48, Drums"), because those
+ * change week to week and the position name ("Vocalist") doesn't say which mic. A note that names a
+ * different mix than the spot is never a match; the role part ("VOX 5") is scored like a position.
+ * 0 means the note says nothing usable about this spot ("NA", blank, or no overlap).
+ */
+function noteScore(slotLabel, note) {
+  const text = String(note || '').trim();
+  if (!text || /^n\/?a$/i.test(text)) return 0;
+  const slotMix = mixNumbers(slotLabel); const noteMix = mixNumbers(text);
+  let mixBonus = 0;
+  if (noteMix.size && slotMix.size) {
+    if (![...noteMix].some((n) => slotMix.has(n))) return 0;
+    mixBonus = 100;
+  }
+  const role = text.replace(/\bmix\s*\d+\b/gi, ' ');
+  const roleScore = scoreMatch(slotRoleText(slotLabel), role);
+  if (!roleScore && !mixBonus) return 0;
+  if (noteMix.size && slotMix.size && roleScore === 0 && role.replace(/[^a-z0-9]/gi, '')) {
+    // The mix agrees but the role contradicts it (e.g. "Mix 8, Keys" on a VOX spot) — trust neither.
+    const roleTokens = labelTokens(role);
+    if (roleTokens.length) return 0;
+  }
+  return mixBonus + roleScore;
+}
+
 function assignMembersToSlots(slots, members) {
   const pool = members.slice();
-  return slots.map((slotLabel) => {
+  const result = slots.map(() => null);
+  const take = (chosen) => {
+    // One spot per person: someone scheduled twice (Leader + Acoustic) must not fill a second spot.
+    const key = chosen.personId || '';
+    for (let i = pool.length - 1; i >= 0; i -= 1) if (pool[i] === chosen || (key && pool[i].personId === key)) pool.splice(i, 1);
+  };
+  // Pass 1 — people whose note names their spot go exactly there, best-fitting pairs first.
+  const pairs = [];
+  slots.forEach((slotLabel, s) => pool.forEach((m) => { const sc = noteScore(slotLabel, m.note); if (sc >= MIN_SCORE) pairs.push({ s, m, sc }); }));
+  pairs.sort((a, b) => b.sc - a.sc);
+  for (const { s, m } of pairs) {
+    if (result[s] || !pool.includes(m)) continue;
+    result[s] = m; take(m);
+  }
+  // Pass 2 — everyone else by Planning Center position, into the spots still open.
+  return result.map((placed, s) => {
+    if (placed) return placed;
+    const slotLabel = slots[s];
     const role = slotRoleText(slotLabel);
     let bestIndex = -1;
     let bestScore = MIN_SCORE - 1;
@@ -128,18 +180,66 @@ function assignMembersToSlots(slots, members) {
       if (score > bestScore) { bestScore = score; bestIndex = i; }
     }
     if (bestIndex < 0) return null;
-    return pool.splice(bestIndex, 1)[0];
+    const chosen = pool[bestIndex];
+    take(chosen);
+    return chosen;
   });
 }
 
+/* ── photos by instrument ──────────────────────────────────────────────
+ * A person can have a photo per instrument, named "Name - Instrument" ("DJ - Drums.jpg",
+ * "DJ - Vocals.jpg"); a photo with no instrument word is their everyday one. Sync picks the photo
+ * whose instrument matches the spot the person is in that week. Instruments group into families so
+ * the usual shorthands agree: Vox/Vocals/Singer, Keys/Piano/Pad/Synth, Drums/Perc, Bass,
+ * Guitar/Electric/Acoustic/Rhythm, Leader. */
+const ROLE_FAMILY = {
+  vocals: 'vocals', keys: 'keys', piano: 'keys', pad: 'keys', synth: 'keys', organ: 'keys',
+  drums: 'drums', percussion: 'drums', bass: 'bass',
+  guitar: 'guitar', electric: 'guitar', acoustic: 'guitar', rhythm: 'guitar', leader: 'leader',
+};
+/** The instrument families a label names ("[LEADER, VOX 1, ACOUSTIC] MIX 1" → leader, vocals, guitar). */
+function roleFamilies(text) {
+  const out = new Set();
+  for (const t of normalizeLabel(text).split(' ')) { const f = ROLE_FAMILY[normalizeToken(t)]; if (f) out.add(f); }
+  return out;
+}
+/** The instrument families a SPOT is for: its bracketed role, else the PCO position it was filled by. */
+function spotFamilies(slotLabel, positionLabel) {
+  const fromSlot = roleFamilies(slotRoleText(slotLabel));
+  return fromSlot.size ? fromSlot : roleFamilies(positionLabel || '');
+}
+/** Split a photo's name into the person and the instruments it shows: "DJ Drums" → "DJ" + {drums}.
+ *  The first word is always the person; instrument words after it are read off, other words
+ *  ("action", "2") are just part of the photo's description. */
+function photoParts(libName) {
+  const words = normalizeLabel(libName).split(' ').filter(Boolean);
+  const roles = new Set(); const person = [];
+  words.forEach((w, i) => {
+    const f = i > 0 ? ROLE_FAMILY[normalizeToken(w)] : null;
+    if (f) roles.add(f); else if (!roles.size) person.push(w);
+  });
+  return { person: person.join(' '), roles };
+}
+/** The key a remembered photo pick is stored under: per person AND instrument, so DJ's drum pick
+ *  never overrides his vocal photo. A spot naming several ("Leader, Vox 1, Acoustic") files under
+ *  its most specific: leader, then vocals, drums, keys, bass, guitar. No family → everyday pick. */
+const ROLE_PRIORITY = ['leader', 'vocals', 'drums', 'keys', 'bass', 'guitar'];
+function photoKey(personId, families) {
+  const f = ROLE_PRIORITY.find((r) => families && families.has(r)) || '';
+  return f ? `${personId}|${f}` : String(personId || '');
+}
+
 /**
  * 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
+ * preferring the most specific. Returns the entry, or null when no library photo is a confident
- * match (e.g. two people share a first name and the photo is first-name-only) — then PCO's photo is used.
+ * match — only then is PCO's headshot used. Several equally good photos ("Mike" and "mike") is
- * `entries` is [{ ...whatever, name }].
+ * not a reason to fall back to PCO: the first of them wins (the booth prefers its own photos).
+ * `entries` is [{ ...whatever, name }]. `want` (optional) is the set of instrument families the
+ * person is on this week: a photo for that instrument beats their everyday photo, which beats a
+ * photo of them on something else — but any photo of theirs still beats PCO's headshot.
  */
-function bestLibraryMatch(pcoName, entries) {
+function bestLibraryMatch(pcoName, entries, want) {
   const target = normalizeLabel(pcoName);
   if (!target) return null;
   const T = target.split(' ').filter(Boolean);
@@ -171,19 +271,39 @@ function bestLibraryMatch(pcoName, entries) {
     if (last && last.length >= 3 && T.includes(last)) return 78;
     return 0;
   };
+  const wanted = want && want.size ? want : null;
   let best = null;
   let bestScore = 0;
-  let tie = false;
   for (const e of entries) {
-    const s = scoreOf(e.name);
+    const parts = photoParts(e.name);
-    if (s > bestScore) { bestScore = s; best = e; tie = false; }
+    let s = scoreOf(parts.roles.size ? parts.person : e.name);
-    else if (s === bestScore && s > 0) tie = true;
+    if (s < 60) continue; // not them
+    if (parts.roles.size && wanted) s += [...parts.roles].some((f) => wanted.has(f)) ? 20 : -20;
+    if (s > bestScore) { bestScore = s; best = e; }
   }
-  if (bestScore < 60 || tie) return null; // no confident / unambiguous winner → PCO photo
+  if (!best) return null; // no confident match → PCO photo
   return best;
 }
 
+/**
+ * Could this library photo be of this Planning Center person? Used when someone drops a photo onto
+ * a synced person's spot, to tell "this is their photo" (remember it) from "put someone else here".
+ * A name match, the same first name ("DJ action" → "DJ McLean"), or first names sharing their
+ * first three letters (a nickname: "Rose" → "Rosaliz").
+ */
+function samePerson(pcoName, libName) {
+  if (bestLibraryMatch(pcoName, [{ name: libName }])) return true;
+  const a = normalizeLabel(pcoName).split(' ')[0] || ''; const b = photoParts(libName).person.split(' ')[0] || '';
+  if (a && a === b) return true;
+  return a.length >= 3 && b.length >= 3 && a.slice(0, 3) === b.slice(0, 3);
+}
+
 module.exports = {
+  samePerson,
+  roleFamilies,
+  spotFamilies,
+  photoParts,
+  photoKey,
   normalizeTeamName,
   isAllowedTeamName,
   bestLibraryMatch,
@@ -194,5 +314,7 @@ module.exports = {
   numbersIn,
   scoreMatch,
   assignMembersToSlots,
+  noteScore,
+  mixNumbers,
   MIN_SCORE,
 };

modules/band-lineup/matching.test.js

@@ -61,7 +61,83 @@ console.log('assignment:', JSON.stringify(out));
   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)
+  // two equally good photos ("Mike" and "mike") → still one of the booth's photos, never PCO's
-  assert.strictEqual(bestLibraryMatch('Chris Smith', [{ id: '1', name: 'Chris' }, { id: '2', name: 'Chris' }]), null, 'ambiguous tie → null');
+  assert.strictEqual(bestLibraryMatch('Mike Powell', [{ id: '1', name: 'Mike' }, { id: '2', name: 'mike' }]).id, '1', 'tie → first library photo');
+  assert.strictEqual(bestLibraryMatch('Joram Lopez', lib), null, 'no photo of them → PCO headshot');
   console.log('bestLibraryMatch: all assertions passed ✓');
 }
+
+// --- one spot per person: someone scheduled twice (Leader + Acoustic) fills one spot only ---
+{
+  const P = (label, name, personId) => ({ label, name, personId });
+  const slots = ['[LEADER, VOX 1, ACOUSTIC] MIX 1', '[GUITAR, 2] MIX 7'];
+  const got = assignMembersToSlots(slots, [P('[Leader]', 'Mike', 'mp'), P('Guitar [Acoustic]', 'Mike', 'mp'), P('Guitar [Rhythm]', 'Craig', 'cs')]).map((m) => (m ? m.name : null));
+  assert.deepStrictEqual(got, ['Mike', 'Craig'], 'Mike once, Craig gets the guitar spot');
+  console.log('one spot per person: all assertions passed ✓');
+}
+
+// --- Planning Center notes place the leader and vocalists (real notes from Oct 25 / Nov 1, 2026) ---
+{
+  const { noteScore } = require('./matching');
+  const NA_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', '[GUITAR, 2] MIX 7', '[VOX 5] MIX 8', '[PIANO]', '[DRUMS]', '[KEYS 2]',
+  ];
+  const P = (label, name, personId, note) => ({ label, name, personId, note });
+  // Listed in the order Planning Center returned them — vocalists alphabetical, not by mic.
+  const oct25 = [
+    P('Vocalist', 'DJ', 'dj', 'Mix 3, VOX 3'), P('[Leader]', 'Mike', 'mp', 'Mix 1, VOX 1'), P('Guitar [Lead]', 'Yeremis', 'yc'),
+    P('Piano/Pad', 'Kevin', 'km'), P('Vocalist', 'Genesis', 'gg', 'Mix 4, VOX 4'), P('Guitar [Rhythm]', 'Craig', 'cs'),
+    P('Guitar [Acoustic]', 'Mike', 'mp'), P('Vocalist', 'Rosaliz', 'rg', 'Mix 2, VOX 2'), P('Drums', 'Luis', 'ld'),
+    P('Vocalist', 'Bianca', 'bb', 'Mix 8, VOX 5'), P('Guitar [Bass]', 'Joram', 'jl'),
+  ];
+  const got = assignMembersToSlots(NA_SLOTS, oct25).map((m) => (m ? m.name : null));
+  assert.deepStrictEqual(got, ['Mike', 'Rosaliz', 'DJ', 'Genesis', 'Yeremis', 'Joram', 'Craig', 'Bianca', 'Kevin', 'Luis', null], 'Oct 25 by notes');
+  // Nov 1: leader note in different case, a drum note with no mix, an "NA" note.
+  const nov1 = [P('Guitar [Acoustic]', 'Mike', 'mp', 'NA'), P('Drums', 'Alex', 'ag', 'DP48, Drums'), P('[Leader]', 'Mike', 'mp', 'Mix 1, Vox 1')];
+  assert.deepStrictEqual(assignMembersToSlots(NA_SLOTS, nov1).map((m) => (m ? m.name : null)).filter(Boolean), ['Mike', 'Alex'], 'Nov 1: Mike once, Alex on drums');
+  assert.strictEqual(assignMembersToSlots(NA_SLOTS, nov1)[9].name, 'Alex', 'DP48, Drums → [DRUMS]');
+  // A note never pulls someone onto a different mix.
+  assert.strictEqual(noteScore('[VOX 2] MIX 2', 'Mix 8, VOX 5'), 0, 'Mix 8 note must not match MIX 2');
+  assert.strictEqual(noteScore('[VOX 5] MIX 8', 'Mix 8, VOX 5') > 0, true, 'Mix 8, VOX 5 matches [VOX 5] MIX 8');
+  assert.strictEqual(noteScore('[VOX 5] MIX 8', 'NA'), 0, 'NA says nothing');
+  assert.strictEqual(noteScore('[VOX 1] MIX 10', 'Mix 1, VOX 1') , 0, 'Mix 1 must not match MIX 10');
+  console.log('notes: all assertions passed ✓');
+}
+
+// --- samePerson: is a dropped photo of the person already in the spot? ---
+{
+  const { samePerson } = require('./matching');
+  assert.ok(samePerson('Rosaliz Gaitan', 'Rose'), 'nickname: Rose → Rosaliz');
+  assert.ok(samePerson('Mike Powell', 'mike'), 'first name, any case');
+  assert.ok(samePerson('Mike Powell', 'Mike Powell action'), 'full name plus words');
+  assert.ok(samePerson('DJ McLean', 'DJ action'), 'short first name plus words');
+  assert.ok(!samePerson('Mike Powell', 'Craig'), 'a different person is a replacement, not their photo');
+  assert.ok(!samePerson('Al Smith', 'Alex'), 'two-letter names never match by prefix');
+  console.log('samePerson: all assertions passed ✓');
+}
+
+// --- a photo per instrument: "DJ - Drums", "DJ - Vocals", plain "DJ" for everything else ---
+{
+  const { bestLibraryMatch, photoParts, spotFamilies, roleFamilies, photoKey } = require('./matching');
+  // File names arrive with the dash turned to a space: "DJ - Drums.jpg" → "DJ Drums".
+  const lib = [{ id: 'e', name: 'DJ' }, { id: 'd', name: 'DJ Drums' }, { id: 'v', name: 'DJ Vocals' }, { id: 'k', name: 'Kevin Piano' }, { id: 'm', name: 'Mike Powell Leader' }];
+  const pick = (name, slot, pos) => { const e = bestLibraryMatch(name, lib, spotFamilies(slot, pos)); return e ? e.id : null; };
+  assert.strictEqual(pick('DJ McLean', '[DRUMS]', 'Drums'), 'd', 'on drums → drum photo');
+  assert.strictEqual(pick('DJ McLean', '[VOX 3] MIX 3', 'Vocalist'), 'v', 'on vocals → vocal photo');
+  assert.strictEqual(pick('DJ McLean', '[KEYS 2]', 'Keys 2'), 'e', 'on keys, no keys photo → everyday photo');
+  assert.strictEqual(pick('DJ McLean', 'STAGE MANAGER', 'Stage Manager'), 'e', 'no instrument → everyday photo');
+  assert.strictEqual(pick('Kevin Michel', '[KEYS 2]', 'Keys 2'), 'k', 'Piano and Keys are one family');
+  assert.strictEqual(pick('Kevin Michel', '[DRUMS]', 'Drums'), 'k', 'only photo is on piano → still his own photo, not PCO');
+  assert.strictEqual(pick('Mike Powell', '[LEADER, VOX 1, ACOUSTIC] MIX 1', '[Leader]'), 'm', 'full name + instrument');
+  assert.strictEqual(pick('Craig Strok', '[DRUMS]', 'Drums'), null, 'nobody else\'s instrument photo is borrowed');
+  assert.deepStrictEqual([...photoParts('DJ Drums action').roles], ['drums'], 'extra words after the instrument are ignored');
+  assert.strictEqual(photoParts('Joshua P').roles.size, 0, 'a plain name has no instrument');
+  assert.strictEqual(photoParts('Keys').person, 'keys', 'the first word is always the person');
+  assert.deepStrictEqual([...spotFamilies('[BASS] MIX 6', 'Guitar [Bass]')], ['bass'], 'the spot decides, not the position');
+  assert.deepStrictEqual([...roleFamilies('Guitar [Rhythm]')], ['guitar'], 'rhythm guitar is guitar');
+  assert.strictEqual(photoKey('dj', new Set(['drums'])), 'dj|drums');
+  assert.strictEqual(photoKey('dj', new Set()), 'dj');
+  assert.strictEqual(photoKey('mp', spotFamilies('[LEADER, VOX 1, ACOUSTIC] MIX 1', '[Leader]')), 'mp|leader', 'leader spot files under leader');
+  console.log('photos by instrument: all assertions passed ✓');
+}

modules/band-lineup/module.json

@@ -1,7 +1,7 @@
 {
   "id": "band-lineup",
   "name": "Band Lineup",
-  "version": "1.11.0",
+  "version": "1.13.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",

modules/band-lineup/server.js

@@ -32,7 +32,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 
-const { isAllowedTeamName, assignMembersToSlots, bestLibraryMatch } = require('./matching');
+const { isAllowedTeamName, assignMembersToSlots, bestLibraryMatch, samePerson, spotFamilies, photoParts, photoKey } = 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(/\/+$/, '');
@@ -219,6 +219,27 @@ module.exports = {
     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
+    // The photo the booth picked for a Planning Center person on an instrument ("<PCO person id>|drums"
+    // → library id; a bare person id is their everyday pick), learned when a library photo is dropped
+    // onto that person. Sync uses it before any name matching.
+    if (!settings.photoFor || typeof settings.photoFor !== 'object') settings.photoFor = {};
+    function rememberPhoto(key, libId) {
+      if (!key || !libId || settings.photoFor[key] === libId) return;
+      settings.photoFor[key] = libId; saveSettings();
+    }
+    // Library photo for a scheduled person in a spot whose instruments are `fams`:
+    //   1. the photo picked for them on this instrument;
+    //   2. a photo named for this instrument ("DJ - Drums");
+    //   3. their everyday pick, else their best-named photo (an other-instrument photo of them
+    //      still beats PCO's headshot).
+    function libraryPhotoFor(personId, name, fams) {
+      const live = (id) => (id && library[id] && library[id].file ? { id, ...library[id] } : null);
+      const forRole = live(settings.photoFor[photoKey(personId, fams)]);
+      if (forRole) return forRole;
+      const m = bestLibraryMatch(name, Object.entries(library).map(([id, v]) => ({ id, name: v.name, file: v.file })), fams);
+      if (m && [...photoParts(m.name).roles].some((f) => fams.has(f))) return m;
+      return live(settings.photoFor[personId]) || (m && m.file ? m : null);
+    }
     function saveSettings() { try { fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2)); } catch (err) { log(`save settings failed: ${err?.message || err}`); } }
 
     const CHOIR_LABEL = 'CHOIR';
@@ -247,7 +268,7 @@ module.exports = {
       return {
         configured: pco.configured, serviceTypeSet: Boolean(serviceTypeId),
         reachable: false, lastError: '', lastFetched: 0, columns,
-        plan: null,
+        plan: settings.lastPlan || null, // the last synced plan, so hand placements after a restart stamp right
         slots: effectiveSlots().map((label, index) => ({ index, label, person: null })),
         library: [], choir: choirOn,
       };
@@ -313,7 +334,7 @@ module.exports = {
      * 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();
+    const cleanNameFromFile = (f) => f.replace(/\.[^.]+$/, '').replace(/[_-]+/g, ' ').replace(/\s+/g, ' ').trim(); // "DJ - Drums.jpg" → "DJ Drums"
     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;
@@ -449,11 +470,13 @@ module.exports = {
       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.
+        // A synced person. Their library photo (if any) is read live, so replacing that photo
+        // updates the board; otherwise the photo chosen at Sync time (a PCO headshot).
         manual = false; personId = e.pco.personId || '';
         name = String(e.pco.name || '').trim();
-        file = e.pco.file || '';
+        const lib = e.pco.libId ? library[e.pco.libId] : null;
-        birthday = e.pco.birthday || '';
+        file = (lib && lib.file) || e.pco.file || '';
+        birthday = e.pco.birthday || (lib && lib.birthday) || '';
       } else if (e.personId) {
         const lib = library[e.personId];
         if (!lib) return null; // its library photo was deleted → slot is empty
@@ -493,7 +516,8 @@ module.exports = {
         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;
+        latest.plan = plan ? { id: String(plan.id), title: plan.title, dates: plan.dates } : null;
+        if (plan) { settings.lastPlan = latest.plan; saveSettings(); }
         if (!plan) { latest.reachable = true; latest.lastError = 'No plan found for that service type.'; }
         else {
 
@@ -511,6 +535,7 @@ module.exports = {
             personId,
             name: String(person?.attributes?.full_name || person?.attributes?.name || m.attributes?.name || 'Unknown').trim() || 'Unknown',
             label: String(m.attributes?.team_position_name || '').trim(),
+            note: String(m.attributes?.notes || '').trim(), // "Mix 8, VOX 5" — where the booth wants them this week
             photoUrl: String(person?.attributes?.photo_url || person?.attributes?.photo_thumbnail_url || '').trim(),
           });
           if (personId) seen.add(personId);
@@ -519,15 +544,29 @@ module.exports = {
         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 }));
+        // A library photo dragged by hand onto a spot for this plan, of someone who IS scheduled
+        // ("Rose" for Rosaliz Gaitan): that's their photo. Remember it, and show them under their
+        // Planning Center name, kept in that spot.
+        for (const [i, e] of Object.entries(board)) {
+          if (!e || !e.personId || e.plan !== String(plan.id) || !library[e.personId]) continue;
+          const libName = library[e.personId].name;
+          const who = [...new Map(members.map((m) => [m.personId, m])).values()].filter((m) => m.personId && samePerson(m.name, libName));
+          if (who.length !== 1) continue; // nobody, or can't tell which — leave it a plain hand placement
+          const m = who[0];
+          rememberPhoto(photoKey(m.personId, spotFamilies(effectiveSlots()[Number(i)] || '', m.label)), e.personId);
+          board[i] = { pco: { name: m.name, file: library[e.personId].file, libId: e.personId, birthday: m.birthday || '', personId: m.personId, position: m.label }, plan: e.plan };
+        }
 
-        // Slots a person is sitting in by hand — don't fill them, and don't place that same person twice.
+        // Slots a person was placed in by hand FOR THIS PLAN — don't fill them, and don't place that
+        // same person twice. A hand placement made for an earlier plan (last week's lineup, or one
+        // from before placements were stamped) is stale: Sync replaces it like any synced slot.
         const eff = effectiveSlots();
+        const planId = String(plan.id);
         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)) {
+          if (e && (e.personId || e.name || e.pco) && e.plan === planId) {
-            const nm = e.personId ? (library[e.personId] && library[e.personId].name) : e.name;
+            const nm = e.pco ? e.pco.name : e.personId ? (library[e.personId] && library[e.personId].name) : e.name;
             if (nm) manualNames.add(normName(nm));
           } else openIdx.push(i);
         }
@@ -537,11 +576,12 @@ module.exports = {
         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
+            // The booth's own photos win over the PCO headshot — the one for the instrument they're on.
-            const file = lib && lib.file ? lib.file : await cachePcoPhoto(m.personId, m.photoUrl);
+            const lib = libraryPhotoFor(m.personId, m.name, spotFamilies(eff[i], m.label));
-            board[String(i)] = { pco: { name: m.name, file, birthday: m.birthday || '', personId: m.personId } };
+            const file = lib ? lib.file : await cachePcoPhoto(m.personId, m.photoUrl);
-          } else if (board[String(i)] && board[String(i)].pco) {
+            board[String(i)] = { pco: { name: m.name, file, libId: lib ? lib.id : '', birthday: m.birthday || '', personId: m.personId, position: m.label } };
-            delete board[String(i)]; // was synced, no longer on the plan
+          } else if (board[String(i)]) {
+            delete board[String(i)]; // synced or stale, and no longer on the plan
           }
         }
         saveBoard();
@@ -580,6 +620,9 @@ module.exports = {
     current = {
       streams, getLatest: () => latest, pco, listPlans, photoDir,
       library, board, saveLibrary, saveBoard, rebuildLocal, refresh: () => syncNow(), slots,
+      planId: () => (latest.plan && latest.plan.id) || '',
+      rememberPhoto,
+      slotLabel: (i) => effectiveSlots()[Number(i)] || '',
       photoUrlFor, libraryList,
       setChoir, choirOn: () => choirOn,
     };
@@ -670,6 +713,10 @@ module.exports = {
         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];
+        // Moving a spot is a hand placement for this plan: Sync must not move it back.
+        const plan = current.planId();
+        if (a) a.plan = plan;
+        if (b) b.plan = plan;
         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();
@@ -684,7 +731,14 @@ module.exports = {
         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: '' };
+        const here = current.board[slot];
+        if (personId && here && here.pco && here.pco.personId && samePerson(here.pco.name, current.library[personId].name)) {
+          // A photo of the person already in this spot: it's their photo now — this week and every
+          // Sync after. They keep their Planning Center name and their spot.
+          // Remembered for this instrument only: DJ's pick on drums leaves his vocal photo alone.
+          current.rememberPhoto(photoKey(here.pco.personId, spotFamilies(current.slotLabel(slot), here.pco.position)), personId);
+          current.board[slot] = { pco: { ...here.pco, libId: personId, file: current.library[personId].file }, plan: current.planId() };
+        } else if (personId) current.board[slot] = { personId, name: '', plan: current.planId() };
         else delete current.board[slot];
         current.saveBoard(); current.rebuildLocal();
         json(res, 200, { ok: true });
@@ -702,6 +756,7 @@ module.exports = {
         const name = String(q.get('name') || '').trim();
         const existing = current.board[index] || { personId: '', name: '' };
         existing.name = name;
+        existing.plan = current.planId();
         if (!existing.personId && !name) delete current.board[index];
         else current.board[index] = existing;
         current.saveBoard(); current.rebuildLocal();

modules/band-lineup/style.css

@@ -230,3 +230,34 @@
   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; }
+
+/* Drag: the floating photo that follows the pointer (appended to <body>, so it scopes itself). */
+[data-module="band-lineup"].bl-drag-ghost {
+  position: fixed; left: 0; top: 0; z-index: 10000; pointer-events: none;
+  width: 72px; aspect-ratio: 3 / 4; margin: -48px 0 0 -36px; border-radius: 8px; overflow: hidden;
+  border: 2px solid var(--accent); background: var(--panel, #222); color: var(--text); font-size: 11px;
+  display: flex; align-items: center; justify-content: center; text-align: center;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45); opacity: 0.92;
+}
+[data-module="band-lineup"].bl-drag-ghost img { width: 100%; height: 100%; object-fit: cover; object-position: center top; }
+[data-module="band-lineup"] .bl-lib-item,
+[data-module="band-lineup"] .bl-edit-slot { -webkit-user-select: none; user-select: none; -webkit-touch-callout: none; }
+[data-module="band-lineup"] .bl-edit-slot img,
+[data-module="band-lineup"] .bl-lib-item img { -webkit-user-drag: none; pointer-events: none; }
+[data-module="band-lineup"] .bl-dragging { opacity: 0.35; }
+[data-module="band-lineup"].bl-is-dragging, [data-module="band-lineup"] .bl-is-dragging { cursor: grabbing; }
+[data-module="band-lineup"] .bl-is-dragging .bl-edit-slot { transition: box-shadow 0.08s; }
+
+/* Editor as two panes that scroll on their own: spots pinned on top, photos below. */
+[data-module="band-lineup"] .bl-editor-split { display: flex; flex-direction: column; overflow: hidden; padding: 0; }
+[data-module="band-lineup"] .bl-pane { overflow: auto; overscroll-behavior: contain; padding: 8px 10px; }
+[data-module="band-lineup"] .bl-board-pane { flex: 0 0 auto; max-height: 55%; border-bottom: 2px solid var(--border); }
+[data-module="band-lineup"] .bl-lib-pane { flex: 1 1 0; min-height: 30%; }
+[data-module="band-lineup"] .bl-lib-search {
+  display: block; width: 100%; box-sizing: border-box; margin: 0 0 8px; padding: 6px 10px;
+  border: 1px solid var(--border); border-radius: 6px; background: var(--panel); color: var(--text); font: inherit; font-size: 0.85em;
+}
+[data-module="band-lineup"] .bl-lib-search:focus { outline: none; border-color: var(--accent); }
+[data-module="band-lineup"] .bl-board-pane .bl-edit-board { margin: 0; }
+[data-module="band-lineup"] .bl-lib-pane .bl-library { border-top: 0; padding-top: 0; }
+[data-module="band-lineup"] .bl-board-pane .bl-edit-photo { aspect-ratio: 1 / 1; }

modules/vista-cues/client.js

@@ -0,0 +1,264 @@
+/* Vista Cues — client part.
+
+   One tile: the cue list most recently fired, big, with how long ago and
+   who fired it; under it the other lists still live, the recent notes, and
+   which senders we are in session with. All of it comes from the server's
+   one `state` event; between events only the "how long ago" clocks move. */
+
+const MINUS_SVG = '<svg viewBox="0 0 16 16" width="13" height="13" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"><path d="M3.5 8h9"/></svg>';
+const PLUS_SVG = '<svg viewBox="0 0 16 16" width="13" height="13" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"><path d="M3.5 8h9M8 3.5v9"/></svg>';
+const CLEAR_SVG = '<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="M6.2 13.5h7.3"/><path d="M2.8 9.6 8.9 3.5a1.4 1.4 0 0 1 2 0l2.1 2.1a1.4 1.4 0 0 1 0 2l-5.9 5.9H5.6L2.8 10.7a.8.8 0 0 1 0-1.1Z"/><path d="m6 6.4 4.1 4.1"/></svg>';
+
+const ACTION_LABEL = {
+  go: 'Go',
+  release: 'Release',
+  releaseAll: 'Release all',
+  pause: 'Pause',
+  back: 'Back',
+  flash: 'Flash',
+  cleared: 'Cleared',
+  '': '—',
+};
+
+function esc(s) {
+  return String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+}
+
+/** 75 000 ms → "1:15", 3 725 000 → "1:02:05". */
+function since(ms) {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const ss = String(s % 60).padStart(2, '0');
+  return h ? `${h}:${String(m).padStart(2, '0')}:${ss}` : `${m}:${ss}`;
+}
+
+function clockTime(ms) {
+  return new Date(ms).toLocaleTimeString([], { hour: 'numeric', minute: '2-digit', second: '2-digit' });
+}
+
+export default function create({ root, moduleApi }) {
+  const prefs = () => moduleApi.instanceSettings || {};
+  const on = (k, dflt = true) => (prefs()[k] === undefined ? dflt : prefs()[k] !== false);
+  const scale = () => Math.min(2.5, Math.max(0.5, Number(prefs().textScale) || 1));
+
+  let state = null;
+  let skew = 0;            // server clock − our clock
+  let stream = null;
+  let tick = null;
+  let el = {};
+  let resizeObserver = null;
+
+  const serverNow = () => Date.now() + skew;
+
+  /* ── fitting the big name to its box ─────────────────────────────── */
+
+  function fit(node) {
+    if (!node || !node.isConnected) return;
+    node.style.fontSize = '';
+    const avail = node.parentElement ? node.parentElement.clientWidth : node.clientWidth;
+    let size = parseFloat(getComputedStyle(node).fontSize) || 16;
+    for (let i = 0; i < 3 && node.scrollWidth > avail + 0.5 && size > 10; i += 1) {
+      size = Math.max(10, size * (avail / node.scrollWidth) * 0.98);
+      node.style.fontSize = `${size}px`;
+    }
+  }
+
+  /* ── drawing ─────────────────────────────────────────────────────── */
+
+  function build() {
+    root.innerHTML = `
+      <div class="vc-root">
+        <div class="vc-offline" hidden></div>
+        <div class="vc-body">
+          <div class="vc-now">
+            <div class="vc-kicker"><span class="vc-pill"></span><span class="vc-ago"></span></div>
+            <div class="vc-name-wrap"><div class="vc-name"></div></div>
+            <div class="vc-meta"></div>
+          </div>
+          <div class="vc-active"></div>
+          <div class="vc-recent"></div>
+          <div class="vc-sources"></div>
+        </div>
+      </div>`;
+    const q = (s) => root.querySelector(s);
+    el = {
+      root: q('.vc-root'),
+      offline: q('.vc-offline'),
+      pill: q('.vc-pill'),
+      ago: q('.vc-ago'),
+      name: q('.vc-name'),
+      meta: q('.vc-meta'),
+      active: q('.vc-active'),
+      recent: q('.vc-recent'),
+      sources: q('.vc-sources'),
+    };
+  }
+
+  function render() {
+    if (!el.root) return;
+    el.root.style.setProperty('--vc-scale', String(scale()));
+    const s = state;
+    if (!s) {
+      el.name.textContent = 'Connecting…';
+      el.root.dataset.tone = 'muted';
+      return;
+    }
+
+    const connected = s.sources.filter((x) => x.connected);
+    const offline = !s.listening || !connected.length;
+    el.root.classList.toggle('is-offline', offline);
+    el.offline.hidden = !offline;
+    el.offline.textContent = !s.listening ? 'Not listening' : 'No MIDI session';
+
+    // Now
+    const cur = s.current;
+    if (cur) {
+      el.root.dataset.tone = cur.state === 'paused' ? 'warn' : 'ok';
+      el.pill.textContent = cur.state === 'paused' ? 'Paused' : 'Live';
+      el.pill.hidden = false;
+      if (el.name.textContent !== cur.name) { el.name.textContent = cur.name; fit(el.name); }
+      const bits = [];
+      if (cur.goes > 1) bits.push(`Go ×${cur.goes}`);
+      if (cur.source) bits.push(cur.source);
+      if (cur.lastAction === 'back') bits.push('Back');
+      el.meta.textContent = bits.join(' · ');
+    } else {
+      el.root.dataset.tone = 'muted';
+      el.pill.hidden = true;
+      const msg = s.rules ? 'No cue list live' : 'No cue lists mapped';
+      if (el.name.textContent !== msg) { el.name.textContent = msg; fit(el.name); }
+      el.meta.textContent = s.rules ? (s.log.length ? '' : 'Waiting for the first cue') : 'Add the cue sheet in /admin → Vista Cues';
+    }
+
+    // Other live lists
+    el.active.hidden = !on('showActive') || !s.active.length;
+    if (!el.active.hidden) {
+      el.active.innerHTML = s.active.map((l) => `
+        <div class="vc-chip${l.state === 'paused' ? ' is-paused' : ''}" title="${esc(l.source || '')}">
+          ${l.group ? `<span class="vc-chip-group">${esc(l.group)}</span>` : ''}
+          <span class="vc-chip-name">${esc(l.name)}</span>
+          <span class="vc-chip-ago" data-since="${l.lastAt}"></span>
+        </div>`).join('');
+    }
+
+    // Recent
+    const showUnmapped = on('showUnmapped', false);
+    const rows = s.log.filter((e) => e.mapped || showUnmapped).slice(0, 12);
+    el.recent.hidden = !on('showRecent') || !rows.length;
+    if (!el.recent.hidden) {
+      el.recent.innerHTML = rows.map((e) => `
+        <div class="vc-row${e.mapped ? '' : ' is-unmapped'}" data-action="${esc(e.action)}">
+          <span class="vc-row-time">${esc(clockTime(e.at))}</span>
+          <span class="vc-row-action">${esc(e.mapped ? (ACTION_LABEL[e.action] ?? e.action) : 'Unmapped')}</span>
+          <span class="vc-row-list">${esc(e.mapped ? e.list : e.trigger)}</span>
+          <span class="vc-row-source">${esc(e.source)}</span>
+        </div>`).join('');
+    }
+
+    // Senders
+    el.sources.hidden = !on('showSources') || !s.sources.length;
+    if (!el.sources.hidden) {
+      el.sources.innerHTML = s.sources.map((x) => `
+        <span class="vc-src${x.connected ? ' is-on' : ''}${x.offNetwork ? ' is-off-network' : ''}" title="${esc((x.offNetwork ? `${x.offNetwork === 'by name' ? 'Set by name' : 'Not on the wired network'} (${s.wiredNetwork}) · ` : '') + (x.connected ? `${x.name || x.label} · ${x.address}` : (x.error || 'Joining…')))}">
+          <span class="vc-dot"></span>${esc(x.label)}
+        </span>`).join('');
+    }
+
+    updateClocks();
+    reportStatus();
+  }
+
+  function updateClocks() {
+    if (!state || !el.root) return;
+    const now = serverNow();
+    const cur = state.current;
+    el.ago.textContent = cur ? since(now - cur.lastAt) : '';
+    el.ago.title = cur ? `Fired ${clockTime(cur.firedAt)}` : '';
+    root.querySelectorAll('[data-since]').forEach((n) => {
+      n.textContent = since(now - Number(n.dataset.since));
+    });
+  }
+
+  function reportStatus() {
+    const s = state;
+    if (!s) return;
+    if (!s.listening) return moduleApi.setStatus('error', s.error || 'Not listening for MIDI');
+    const connected = s.sources.filter((x) => x.connected);
+    const waiting = s.sources.filter((x) => !x.connected);
+    const off = s.sources.filter((x) => x.offNetwork);
+    if (off.length) return moduleApi.setStatus('error', `${off.map((x) => x.label).join(', ')} not on the wired network (${s.wiredNetwork})`);
+    if (!connected.length) {
+      const why = waiting.length ? `Joining ${waiting.map((x) => `${x.label}${x.error ? ` (${x.error})` : ''}`).join(', ')}` : 'No MIDI session connected';
+      return moduleApi.setStatus('error', why);
+    }
+    const msg = `Hearing ${connected.map((x) => x.label).join(', ')}${waiting.length ? ` · not ${waiting.map((x) => x.label).join(', ')}` : ''}`;
+    return moduleApi.setStatus(waiting.length ? 'connecting' : 'ok', msg);
+  }
+
+  function take(next) {
+    if (!next) return;
+    skew = Number(next.now) ? Number(next.now) - Date.now() : 0;
+    state = next;
+    render();
+  }
+
+  async function refresh() {
+    try {
+      const r = await moduleApi.fetch('/state');
+      if (r.ok) take((await r.json()).state);
+    } catch { /* the stream will say so */ }
+  }
+
+  /* ── title bar ───────────────────────────────────────────────────── */
+
+  function bump(delta) {
+    const next = Math.round(Math.min(2.5, Math.max(0.5, scale() + delta)) * 10) / 10;
+    moduleApi.saveInstanceSettings({ textScale: next });
+    render();
+    fit(el.name);
+  }
+
+  return {
+    start() {
+      build();
+      render();
+      moduleApi.header.addButton({ icon: MINUS_SVG, title: 'Smaller text', onClick: () => bump(-0.1) });
+      moduleApi.header.addButton({ icon: PLUS_SVG, title: 'Larger text', onClick: () => bump(0.1) });
+      moduleApi.header.addButton({
+        icon: CLEAR_SVG,
+        title: 'Clear live lists',
+        async onClick() {
+          try { await moduleApi.fetch('/clear', { method: 'POST' }); } catch { /* status says why */ }
+        },
+      });
+      moduleApi.setStatus('connecting', 'Connecting…');
+      stream = moduleApi.sse('/stream', {
+        open() { refresh(); },
+        error() { moduleApi.setStatus('error', 'Lost connection to ProdDash'); },
+        events: {
+          state(e) {
+            try { take(JSON.parse(e.data)); } catch { /* malformed frame */ }
+          },
+        },
+      });
+      refresh();
+      tick = setInterval(updateClocks, 1000);
+      if (typeof ResizeObserver === 'function') {
+        resizeObserver = new ResizeObserver(() => fit(el.name));
+        resizeObserver.observe(root);
+      }
+    },
+    stop() {
+      clearInterval(tick);
+      tick = null;
+      if (stream) { stream.close(); stream = null; }
+      if (resizeObserver) { resizeObserver.disconnect(); resizeObserver = null; }
+      root.innerHTML = '';
+      el = {};
+    },
+    onResize() {
+      fit(el.name);
+    },
+  };
+}

modules/vista-cues/mapping.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * The admin page's "Cue lists" text → rules, and MIDI events → what Vista
+ * was told to do.
+ *
+ * One rule per line, the way it reads on a cue sheet:
+ *
+ *   60 = Walk-in                  note 60 fires Go on "Walk-in"
+ *   C3 = Worship 1                note names work too (see "Middle C" in admin)
+ *   61 release Walk-in            release a list
+ *   62 pause Walk-in              also: back, pause, go (the default)
+ *   127 release all               every list off
+ *   ch2:64 = Message              only on MIDI channel 2 (otherwise any channel)
+ *   pc5 = Baptism                 a program change instead of a note
+ *   65 = "Back Lights"            quote a name that starts with an action word
+ *   # anything after a # is a comment
+ *
+ * Groups: a line "[Colors]" starts a group, and every rule below it belongs
+ * to it until the next "[…]" ("[]" ends grouping). A Go in a group replaces
+ * whichever list of that group was live — firing "Blue" ends "Red" — which is
+ * how a sheet without release notes still says what is on. The first group
+ * in the sheet is the headline the tile shows largest.
+ *
+ *   30 flash Blinder Flash 1      a momentary hit: logged, never left live
+ *
+ * The separator between the trigger and the rest may be "=", "-", ":", "→",
+ * a tab or just a space, so a column pasted from a spreadsheet works.
+ */
+
+const NOTE_NAMES = { c: 0, d: 2, e: 4, f: 5, g: 7, a: 9, b: 11 };
+const NAMES_SHARP = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
+
+const ACTIONS = [
+  // Longest first, so "release all" wins over "release".
+  [/^(release[\s_-]*all|all[\s_-]*off|releaseall|clear)\b/i, 'releaseAll'],
+  [/^(release|off|stop|kill)\b/i, 'release'],
+  [/^(pause|hold)\b/i, 'pause'],
+  [/^(back|previous|prev)\b/i, 'back'],
+  [/^(flash|hit|momentary)\b/i, 'flash'],
+  [/^(go|fire|play|start)\b/i, 'go'],
+];
+
+/** Octave offset: with middle C (note 60) called "C3", C-2 is note 0; with "C4", C-1 is. */
+function octaveBase(middleC) {
+  return middleC === 'C4' ? 1 : 2;
+}
+
+/** "F#2" → note number, or null. */
+function noteFromName(token, middleC) {
+  const m = /^([a-g])(#|♯|b|♭)?(-?\d+)$/i.exec(token);
+  if (!m) return null;
+  let pc = NOTE_NAMES[m[1].toLowerCase()];
+  if (m[2] === '#' || m[2] === '♯') pc += 1;
+  if (m[2] === 'b' || m[2] === '♭') pc -= 1;
+  const n = (Number(m[3]) + octaveBase(middleC)) * 12 + pc;
+  return n >= 0 && n <= 127 ? n : null;
+}
+
+function noteName(n, middleC) {
+  return `${NAMES_SHARP[n % 12]}${Math.floor(n / 12) - octaveBase(middleC)}`;
+}
+
+/**
+ * Parse the whole text. Returns `{ rules, errors, groups }` (groups in sheet order); a line that can't be read
+ * is reported (line number + why) and skipped, never fatal.
+ */
+function parseMapping(text, { middleC = 'C3' } = {}) {
+  const rules = [];
+  const errors = [];
+  const groups = [];
+  let group = '';
+  String(text || '').split(/\r?\n/).forEach((raw, i) => {
+    // A comment is a # that starts the line or follows a space ("C#3" and "Song #2" are not).
+    const line = raw.replace(/(^|\s)#(\s.*|$)/, '').trim();
+    if (!line) return;
+    const header = /^\[(.*)\]$/.exec(line);
+    if (header) {
+      group = header[1].trim();
+      if (group && !groups.includes(group)) groups.push(group);
+      return;
+    }
+    const m = /^(?:ch(?:annel)?\s*(\d{1,2})\s*[:/]\s*)?(pc\s*\d{1,3}|note\s*\d{1,3}|\d{1,3}|[a-g](?:#|♯|b|♭)?-?\d)\s*(?:[=:\t→>|,-]+\s*|\s+|$)(.*)$/i.exec(line);
+    if (!m) {
+      errors.push({ line: i + 1, text: raw.trim(), why: 'starts with no note' });
+      return;
+    }
+    const channel = m[1] ? Number(m[1]) : null;
+    if (channel != null && (channel < 1 || channel > 16)) {
+      errors.push({ line: i + 1, text: raw.trim(), why: 'channel must be 1–16' });
+      return;
+    }
+    const trig = m[2].replace(/\s+/g, '').toLowerCase();
+    let kind = 'note';
+    let number;
+    if (trig.startsWith('pc')) {
+      kind = 'program';
+      number = Number(trig.slice(2));
+    } else if (trig.startsWith('note')) {
+      number = Number(trig.slice(4));
+    } else if (/^\d+$/.test(trig)) {
+      number = Number(trig);
+    } else {
+      number = noteFromName(m[2].replace(/\s+/g, ''), middleC);
+    }
+    if (number == null || !Number.isInteger(number) || number < 0 || number > 127) {
+      errors.push({ line: i + 1, text: raw.trim(), why: 'note must be 0–127' });
+      return;
+    }
+    let rest = m[3].trim();
+    let action = 'go';
+    const quoted = (t) => /^"(.*)"$/.exec(t);
+    for (const [re, a] of quoted(rest) ? [] : ACTIONS) {
+      const am = re.exec(rest);
+      if (am) {
+        action = a;
+        rest = rest.slice(am[0].length).replace(/^[\s=:→>|,-]+/, '').trim();
+        break;
+      }
+    }
+    const q = quoted(rest);
+    if (q) rest = q[1].trim();
+    if (action !== 'releaseAll' && !rest) {
+      errors.push({ line: i + 1, text: raw.trim(), why: 'no cue list name' });
+      return;
+    }
+    rules.push({ line: i + 1, channel, kind, number, action, list: action === 'releaseAll' ? '' : rest, group });
+  });
+  return { rules, errors, groups };
+}
+
+/** The first rule a MIDI event matches, or null. Only note-ons and program changes fire anything. */
+function match(rules, event) {
+  let kind;
+  let number;
+  if (event.type === 'noteon') { kind = 'note'; number = event.note; }
+  else if (event.type === 'program') { kind = 'program'; number = event.program; }
+  else return null;
+  return rules.find((r) => r.kind === kind && r.number === number && (r.channel == null || r.channel === event.channel)) || null;
+}
+
+/** "Note 60 (C3) · ch 1" — how an event is named on the tile. */
+function triggerLabel(event, middleC) {
+  if (event.type === 'program') return `PC ${event.program} · ch ${event.channel}`;
+  return `Note ${event.note} (${noteName(event.note, middleC)}) · ch ${event.channel}`;
+}
+
+module.exports = { parseMapping, match, noteName, noteFromName, triggerLabel };

modules/vista-cues/module.json

@@ -0,0 +1,173 @@
+{
+  "id": "vista-cues",
+  "name": "Vista Cues",
+  "version": "1.1.0",
+  "proddash": ">=1.5.0",
+  "description": "Which Vista 3 cue lists are live: hears the network MIDI that ProPresenter and Tracks send Vista",
+  "permissions": [
+    {
+      "kind": "local-network",
+      "reason": "Joining the network MIDI sessions that fire Vista's cue lists"
+    }
+  ],
+  "client": "client.js",
+  "server": "server.js",
+  "style": "style.css",
+  "minSize": {
+    "w": 2,
+    "h": 1
+  },
+  "defaultSize": {
+    "w": 5,
+    "h": 4
+  },
+  "configSchema": {
+    "source1Name": {
+      "type": "string",
+      "label": "Name",
+      "default": "ProPresenter",
+      "group": "First sender",
+      "help": "What the tile calls notes from this machine."
+    },
+    "source1": {
+      "type": "endpoint",
+      "label": "Session",
+      "default": {
+        "host": "",
+        "port": 5004
+      },
+      "group": "First sender",
+      "help": "The Mac whose network MIDI session sends Vista its notes, and that session's port (Audio MIDI Setup → Window → Show MIDI Studio → Network; usually 5004)."
+    },
+    "source2Name": {
+      "type": "string",
+      "label": "Name",
+      "default": "Tracks",
+      "group": "Second sender"
+    },
+    "source2": {
+      "type": "endpoint",
+      "label": "Session",
+      "default": {
+        "host": "",
+        "port": 5004
+      },
+      "group": "Second sender",
+      "help": "Leave the host empty if this machine joins us from its own side instead."
+    },
+    "source3Name": {
+      "type": "string",
+      "label": "Name",
+      "default": "Companion",
+      "group": "Third sender"
+    },
+    "source3": {
+      "type": "endpoint",
+      "label": "Session",
+      "default": {
+        "host": "",
+        "port": 5004
+      },
+      "group": "Third sender",
+      "help": "Companion on this machine counts too: its network session's host and port (this Mac's own name works)."
+    },
+    "cueLists": {
+      "type": "text",
+      "label": "Cue lists",
+      "default": "",
+      "group": "Cue lists",
+      "help": "One per line from the cue sheet: 60 = Walk-in · 61 release Walk-in · 127 release all · 30 flash Blinder 1 (momentary). A line like [Colors] starts a group: a Go in a group replaces that group's live list; the first group is the tile's headline. Also pause, back, note names, ch2:64, pc5, and \"quotes\" around a name starting with one of those words."
+    },
+    "middleC": {
+      "type": "select",
+      "label": "Middle C",
+      "default": "C3",
+      "options": [
+        {
+          "value": "C3",
+          "label": "C3 (Ableton, Yamaha)"
+        },
+        {
+          "value": "C4",
+          "label": "C4 (Logic, scientific)"
+        }
+      ],
+      "group": "Cue lists",
+      "help": "Only matters for note names in the sheet. Note 60 is middle C either way."
+    },
+    "headTakesOver": {
+      "type": "switch",
+      "label": "Main group takes over",
+      "default": true,
+      "group": "Cue lists",
+      "help": "On: a Go in the sheet's first [group] (the main scene) clears every other live list, as a new scene takes over the look. FX fired after it layer on top again."
+    },
+    "exclusive": {
+      "type": "switch",
+      "label": "Go releases others",
+      "default": false,
+      "group": "Cue lists",
+      "help": "On: a Go replaces every other live list, groups or not. Leave off when lists stack, and use groups instead."
+    },
+    "sessionName": {
+      "type": "string",
+      "label": "Session name",
+      "default": "ProdDash Lighting",
+      "group": "This machine",
+      "help": "How ProdDash appears in other Macs' Audio MIDI Setup Directory."
+    },
+    "sessionPort": {
+      "type": "number",
+      "label": "Session port",
+      "default": 5040,
+      "min": 1024,
+      "max": 65534,
+      "group": "This machine",
+      "help": "UDP; this one and the next are used. Anything not already taken by a MIDI session on this machine."
+    },
+    "advertise": {
+      "type": "switch",
+      "label": "Bonjour",
+      "default": true,
+      "group": "This machine",
+      "help": "List this machine in Audio MIDI Setup's Directory on the network (macOS)."
+    },
+    "wiredNetwork": {
+      "type": "string",
+      "label": "Wired network",
+      "default": "",
+      "group": "This machine",
+      "help": "The network MIDI must come over, like 10.1.0.0/16 (several: comma between). A sender set by name or to an address outside it shows red here and on the tile; it still joins. Empty: any network."
+    }
+  },
+  "configGroups": {
+    "First sender": {
+      "help": "ProdDash joins the senders' network MIDI sessions, like Vista does, so it hears every note Vista hears. On each sender, in Audio MIDI Setup → MIDI Network Setup, the session must be enabled and 'Who may connect to me' set to Anyone. Or skip the address and connect to \"ProdDash Lighting\" from that Mac's Directory instead."
+    },
+    "This machine": {
+      "collapsed": true
+    }
+  },
+  "instanceSchema": {
+    "showActive": {
+      "type": "switch",
+      "label": "Other lists",
+      "default": true
+    },
+    "showRecent": {
+      "type": "switch",
+      "label": "Recent",
+      "default": true
+    },
+    "showSources": {
+      "type": "switch",
+      "label": "Senders",
+      "default": true
+    },
+    "showUnmapped": {
+      "type": "switch",
+      "label": "Unmapped notes",
+      "default": false
+    }
+  }
+}

modules/vista-cues/rtpmidi.js

@@ -0,0 +1,630 @@
+'use strict';
+
+/**
+ * A listen-only RTP-MIDI (AppleMIDI) session participant, in plain Node.
+ *
+ * This is the protocol behind a macOS "Network" MIDI session (Audio MIDI
+ * Setup → MIDI Network Setup) and rtpMIDI on Windows: two UDP ports, a
+ * control port P and a data port P+1. A session sends every MIDI message to
+ * every participant it is connected to, so joining the same session Vista is
+ * in hears exactly the notes Vista hears.
+ *
+ * Both ways of joining work:
+ *  - someone invites us (we show up in Audio MIDI Setup's Directory, or they
+ *    add our address by hand) and we accept anyone;
+ *  - we invite them (`invite(host, port)`), and keep re-inviting until they
+ *    accept, then keep the connection alive with clock syncs.
+ *
+ * We never send MIDI. Packet layouts follow Apple's AppleMIDI session
+ * protocol and RFC 6295 (RTP payload for MIDI).
+ */
+
+const dgram = require('dgram');
+const dns = require('dns');
+const crypto = require('crypto');
+const { EventEmitter } = require('events');
+
+const SIG = 0xffff;
+const CMD = { IN: 0x494e, OK: 0x4f4b, NO: 0x4e4f, BY: 0x4259, CK: 0x434b, RS: 0x5253 };
+const PROTOCOL_VERSION = 2;
+
+const INVITE_RETRY_MS = 1500;     // between invitation attempts while setting up
+const INVITE_ATTEMPTS = 12;       // then give up for a while…
+const REINVITE_MS = 5000;         // …and start over after this long
+const SYNC_FAST_MS = 1500;        // first few clock syncs, close together
+const SYNC_MS = 10000;            // then this often, as macOS does
+const SYNC_TIMEOUT_MS = 25000;    // no sync answer for this long → connection is gone
+const IDLE_MS = 90000;            // an inbound participant we have not heard from at all
+const FEEDBACK_MS = 1000;         // receiver feedback (lets the sender trim its journal)
+
+/** The session clock: 100 µs ticks since this process started the session. */
+function makeClock() {
+  const t0 = process.hrtime.bigint();
+  return () => (process.hrtime.bigint() - t0) / 100000n;
+}
+
+function randomU32() {
+  return crypto.randomBytes(4).readUInt32BE(0);
+}
+
+/* ── packets ─────────────────────────────────────────────────────────── */
+
+function sessionPacket(cmd, token, ssrc, name) {
+  const nameBuf = name == null ? Buffer.alloc(0) : Buffer.from(`${name}\0`, 'utf8');
+  const b = Buffer.alloc(16 + nameBuf.length);
+  b.writeUInt16BE(SIG, 0);
+  b.writeUInt16BE(cmd, 2);
+  b.writeUInt32BE(PROTOCOL_VERSION, 4);
+  b.writeUInt32BE(token >>> 0, 8);
+  b.writeUInt32BE(ssrc >>> 0, 12);
+  nameBuf.copy(b, 16);
+  return b;
+}
+
+function syncPacket(ssrc, count, ts) {
+  const b = Buffer.alloc(36);
+  b.writeUInt16BE(SIG, 0);
+  b.writeUInt16BE(CMD.CK, 2);
+  b.writeUInt32BE(ssrc >>> 0, 4);
+  b.writeUInt8(count, 8);
+  for (let i = 0; i < 3; i++) b.writeBigUInt64BE(BigInt.asUintN(64, ts[i] || 0n), 12 + i * 8);
+  return b;
+}
+
+function feedbackPacket(ssrc, seq) {
+  const b = Buffer.alloc(12);
+  b.writeUInt16BE(SIG, 0);
+  b.writeUInt16BE(CMD.RS, 2);
+  b.writeUInt32BE(ssrc >>> 0, 4);
+  b.writeUInt16BE(seq & 0xffff, 8);
+  return b;
+}
+
+/** A session command (IN/OK/NO/BY/CK/RS), or null when it isn't one. */
+function parseSession(buf) {
+  if (buf.length < 4 || buf.readUInt16BE(0) !== SIG) return null;
+  const cmd = buf.readUInt16BE(2);
+  if (cmd === CMD.CK) {
+    if (buf.length < 36) return null;
+    return {
+      cmd,
+      ssrc: buf.readUInt32BE(4),
+      count: buf.readUInt8(8),
+      ts: [buf.readBigUInt64BE(12), buf.readBigUInt64BE(20), buf.readBigUInt64BE(28)],
+    };
+  }
+  if (cmd === CMD.RS) {
+    if (buf.length < 12) return null;
+    return { cmd, ssrc: buf.readUInt32BE(4), seq: buf.readUInt16BE(8) };
+  }
+  if (cmd === CMD.IN || cmd === CMD.OK || cmd === CMD.NO || cmd === CMD.BY) {
+    if (buf.length < 16) return null;
+    let name = '';
+    if (buf.length > 16) {
+      const end = buf.indexOf(0, 16);
+      name = buf.toString('utf8', 16, end < 0 ? buf.length : end);
+    }
+    return { cmd, version: buf.readUInt32BE(4), token: buf.readUInt32BE(8), ssrc: buf.readUInt32BE(12), name };
+  }
+  return null;
+}
+
+/** Data bytes that follow a status byte (sysex is handled separately). */
+function dataLength(status) {
+  const hi = status & 0xf0;
+  if (hi === 0xc0 || hi === 0xd0) return 1;
+  if (hi < 0xf0) return 2;
+  if (status === 0xf1 || status === 0xf3) return 1;
+  if (status === 0xf2) return 2;
+  return 0;
+}
+
+/**
+ * The MIDI commands in one RTP-MIDI packet (RFC 6295 §3), as
+ * `{ status, data: [..] }` in order. Journal data is ignored: we only show
+ * what is happening, and a note lost on the wire is one Vista also missed.
+ */
+function parseRtpMidi(buf) {
+  if (buf.length < 13 || (buf[0] >> 6) !== 2) return null;
+  const cc = buf[0] & 0x0f;
+  const ext = Boolean(buf[0] & 0x10);
+  const seq = buf.readUInt16BE(2);
+  const ssrc = buf.readUInt32BE(8);
+  let off = 12 + cc * 4;
+  if (ext) {
+    if (buf.length < off + 4) return null;
+    off += 4 + buf.readUInt16BE(off + 2) * 4;
+  }
+  if (off >= buf.length) return null;
+  const header = buf[off];
+  const big = Boolean(header & 0x80);
+  const zero = Boolean(header & 0x20);
+  let len = header & 0x0f;
+  if (big) {
+    if (off + 1 >= buf.length) return null;
+    len = (len << 8) | buf[off + 1];
+    off += 2;
+  } else {
+    off += 1;
+  }
+  const end = Math.min(buf.length, off + len);
+  const messages = [];
+  let running = 0;
+  let first = true;
+  while (off < end) {
+    if (!first || zero) {
+      // Delta time: 1–4 octets, high bit means "more follow".
+      let n = 0;
+      while (off < end && (buf[off] & 0x80) && n < 3) { off++; n++; }
+      off++;
+      if (off >= end) break;
+    }
+    first = false;
+    let status = buf[off];
+    if (status & 0x80) {
+      off++;
+    } else if (running) {
+      status = running;
+    } else {
+      break; // data byte with nothing to run on: give up on this packet
+    }
+    if (status === 0xf0 || status === 0xf7) {
+      // A sysex, or a segment of one: runs to F7 (end), F0 (more follows) or F4 (cancelled).
+      const start = off;
+      while (off < end && buf[off] !== 0xf7 && buf[off] !== 0xf0 && buf[off] !== 0xf4) off++;
+      const data = Array.from(buf.subarray(start, off));
+      off++;
+      messages.push({ status, data });
+      running = 0;
+      continue;
+    }
+    if (status < 0xf0) running = status;
+    else if (status < 0xf8) running = 0; // system common cancels running status; realtime doesn't
+    const n = dataLength(status);
+    if (off + n > end) break;
+    messages.push({ status, data: Array.from(buf.subarray(off, off + n)) });
+    off += n;
+  }
+  return { seq, ssrc, messages };
+}
+
+/** `{ status, data }` → a plain event, or null for what nobody here cares about. */
+function describe(msg) {
+  const hi = msg.status & 0xf0;
+  const channel = (msg.status & 0x0f) + 1;
+  if (hi === 0x90 && msg.data[1] > 0) return { type: 'noteon', channel, note: msg.data[0], velocity: msg.data[1] };
+  if (hi === 0x80 || (hi === 0x90 && msg.data[1] === 0)) return { type: 'noteoff', channel, note: msg.data[0] };
+  if (hi === 0xc0) return { type: 'program', channel, program: msg.data[0] };
+  if (hi === 0xb0) return { type: 'cc', channel, controller: msg.data[0], value: msg.data[1] };
+  return null;
+}
+
+/* ── the session ─────────────────────────────────────────────────────── */
+
+class Session extends EventEmitter {
+  /**
+   * @param {{ name: string, port: number, log?: Function }} opts
+   * Events: 'midi' ({ participant, event }), 'change' (participants or
+   * listening changed), 'listening' (both ports bound).
+   */
+  constructor({ name, port, log }) {
+    super();
+    this.name = name || 'ProdDash';
+    this.port = port;
+    this.log = log || (() => {});
+    this.ssrc = randomU32();
+    this.now = makeClock();
+    this.control = null;
+    this.data = null;
+    this.participants = new Map(); // key → participant
+    this.invites = new Map();      // key "host:port" → outbound invitation
+    this.strangers = new Map();    // address → when we last told it we're not in its session
+    this.timers = new Set();
+    this.stopped = false;
+    this.error = '';
+  }
+
+  /**
+   * Open both ports. Resolves once both are bound — or once the first try
+   * failed, with `error` set. A port that is busy (our own previous session
+   * still closing after a config save, or another program) is retried every
+   * few seconds for as long as the session runs; 'listening' fires when it
+   * finally binds.
+   */
+  start() {
+    this.every(FEEDBACK_MS, () => this.sendFeedback());
+    this.every(5000, () => this.reap());
+    return new Promise((resolve) => {
+      let first = true;
+      const attempt = (delay) => this.later(delay, async () => {
+        const ok = await this.bind();
+        if (ok) {
+          this.error = '';
+          this.emit('listening');
+          this.emit('change');
+        } else {
+          this.emit('change');
+          attempt(first ? 250 : 3000);
+        }
+        if (first) { first = false; resolve(ok); }
+      });
+      attempt(0);
+    });
+  }
+
+  /** Bind control and data sockets together; on failure close both. */
+  bind() {
+    const open = (port, which) => new Promise((resolve) => {
+      const sock = dgram.createSocket('udp4');
+      const fail = (e) => {
+        try { sock.close(); } catch { /* not open */ }
+        resolve({ sock: null, port, e });
+      };
+      sock.once('error', fail);
+      sock.bind(port, () => {
+        sock.removeListener('error', fail);
+        sock.on('error', (e) => this.log(`socket error on ${port}: ${e.message}`));
+        sock.on('message', (buf, rinfo) => {
+          try { this.onPacket(buf, rinfo, which); } catch (e) { this.log(`bad packet from ${rinfo.address}: ${e.message}`); }
+        });
+        resolve({ sock, port });
+      });
+    });
+    return Promise.all([open(this.port, 'control'), open(this.port + 1, 'data')]).then(([c, d]) => {
+      if (this.stopped || !c.sock || !d.sock) {
+        for (const x of [c, d]) if (x.sock) { try { x.sock.close(); } catch { /* closed */ } }
+        const bad = !c.sock ? c : d;
+        if (bad.e) {
+          const msg = bad.e.code === 'EADDRINUSE'
+            ? `UDP port ${bad.port} is in use on this machine — pick another session port in /admin`
+            : `UDP port ${bad.port}: ${bad.e.message}`;
+          if (msg !== this.error) this.log(msg);
+          this.error = msg;
+        }
+        return false;
+      }
+      this.control = c.sock;
+      this.data = d.sock;
+      return true;
+    });
+  }
+
+  stop() {
+    this.stopped = true;
+    for (const t of this.timers) { clearTimeout(t); clearInterval(t); }
+    this.timers.clear();
+    const control = this.control;
+    const data = this.data;
+    const close = () => {
+      for (const s of [control, data]) { try { s && s.close(); } catch { /* closed */ } }
+    };
+    // Say goodbye, then close once the goodbyes have left (a config save
+    // re-inits straight away and wants these ports back).
+    const byes = [...this.participants.values()].filter((p) => p.connected);
+    let left = byes.length;
+    if (!control || !left) close();
+    else {
+      for (const p of byes) {
+        try {
+          control.send(sessionPacket(CMD.BY, p.token, this.ssrc), p.controlPort, p.address, () => { if (--left === 0) close(); });
+        } catch { if (--left === 0) close(); }
+      }
+    }
+    this.control = null;
+    this.data = null;
+    this.participants.clear();
+    this.invites.clear();
+  }
+
+  every(ms, fn) {
+    const t = setInterval(fn, ms);
+    t.unref?.();
+    this.timers.add(t);
+    return t;
+  }
+
+  later(ms, fn) {
+    const t = setTimeout(() => { this.timers.delete(t); if (!this.stopped) fn(); }, ms);
+    t.unref?.();
+    this.timers.add(t);
+    return t;
+  }
+
+  send(sock, buf, port, address) {
+    if (!sock || this.stopped) return;
+    try { sock.send(buf, port, address); } catch { /* socket closed */ }
+  }
+
+  /** Every participant, for display. */
+  list() {
+    return [...this.participants.values()].map((p) => ({
+      name: p.name,
+      address: p.address,
+      port: p.controlPort,
+      connected: p.connected,
+      outbound: p.outbound,
+      lastHeard: p.lastHeard || null,
+      since: p.since || null,
+    }));
+  }
+
+  /* — outbound invitations — */
+
+  /**
+   * Keep a connection to the session at host:port. Re-invites on its own
+   * whenever the connection drops. Returns the invitation's state object.
+   */
+  invite(host, port, label) {
+    const key = `${host}:${port}`;
+    if (this.invites.has(key)) return this.invites.get(key);
+    const inv = { key, host, port, label: label || host, address: '', token: 0, attempts: 0, stage: 'idle', error: '', timer: null };
+    this.invites.set(key, inv);
+    this.beginInvite(inv);
+    return inv;
+  }
+
+  beginInvite(inv) {
+    if (this.stopped || !this.invites.has(inv.key)) return;
+    dns.lookup(inv.host, { family: 4 }, (err, address) => {
+      if (this.stopped) return;
+      if (err) {
+        inv.error = `can't find ${inv.host}`;
+        inv.stage = 'idle';
+        this.emit('change');
+        this.later(REINVITE_MS, () => this.beginInvite(inv));
+        return;
+      }
+      inv.address = address;
+      // Already in a session with that machine (it invited us)? Nothing to do.
+      const existing = this.findByAddress(address, inv.port);
+      if (existing && existing.connected) {
+        existing.label = inv.label;
+        inv.stage = 'connected';
+        inv.error = '';
+        this.emit('change');
+        return;
+      }
+      inv.token = randomU32();
+      inv.attempts = 0;
+      inv.stage = 'control';
+      this.sendInvite(inv);
+    });
+  }
+
+  sendInvite(inv) {
+    if (this.stopped || !this.invites.has(inv.key)) return;
+    if (inv.stage !== 'control' && inv.stage !== 'data') return;
+    if (inv.attempts >= INVITE_ATTEMPTS) {
+      inv.error = inv.error || 'no answer';
+      inv.stage = 'idle';
+      this.emit('change');
+      this.later(REINVITE_MS, () => this.beginInvite(inv));
+      return;
+    }
+    inv.attempts++;
+    const sock = inv.stage === 'control' ? this.control : this.data;
+    const port = inv.stage === 'control' ? inv.port : inv.port + 1;
+    this.send(sock, sessionPacket(CMD.IN, inv.token, this.ssrc, this.name), port, inv.address);
+    clearTimeout(inv.timer);
+    inv.timer = this.later(INVITE_RETRY_MS, () => this.sendInvite(inv));
+  }
+
+  inviteFor(rinfo, token) {
+    for (const inv of this.invites.values()) {
+      if (inv.token === token && inv.address === rinfo.address) return inv;
+    }
+    return null;
+  }
+
+  findByAddress(address, controlPort) {
+    for (const p of this.participants.values()) {
+      if (p.address === address && (controlPort == null || p.controlPort === controlPort)) return p;
+    }
+    return null;
+  }
+
+  /* — packets in — */
+
+  onPacket(buf, rinfo, which) {
+    const s = parseSession(buf);
+    if (!s) {
+      if (which === 'data') this.onRtp(buf, rinfo);
+      return;
+    }
+    const sock = which === 'control' ? this.control : this.data;
+    switch (s.cmd) {
+      case CMD.IN: return this.onInvitation(s, rinfo, which, sock);
+      case CMD.OK: return this.onAccepted(s, rinfo, which);
+      case CMD.NO: return this.onRejected(s, rinfo);
+      case CMD.BY: return this.onBye(s, rinfo);
+      case CMD.CK: return this.onSync(s, rinfo);
+      default: return undefined; // RS from a peer: nothing for a listener to do
+    }
+  }
+
+  onInvitation(s, rinfo, which, sock) {
+    // We accept anyone: being in more sessions only means hearing more cues.
+    this.send(sock, sessionPacket(CMD.OK, s.token, this.ssrc, this.name), rinfo.port, rinfo.address);
+    const key = `in:${s.ssrc}`;
+    let p = this.participants.get(key);
+    if (which === 'control') {
+      if (!p) {
+        p = {
+          key, ssrc: s.ssrc, token: s.token, name: s.name || rinfo.address, label: '',
+          address: rinfo.address, controlPort: rinfo.port, dataPort: rinfo.port + 1,
+          outbound: false, connected: false, lastSeq: -1, fedBack: -1, lastHeard: Date.now(), since: 0,
+        };
+        this.participants.set(key, p);
+        this.log(`invited by "${p.name}" at ${rinfo.address}:${rinfo.port}`);
+      } else {
+        p.token = s.token;
+        p.controlPort = rinfo.port;
+        p.name = s.name || p.name;
+      }
+    } else if (p) {
+      p.dataPort = rinfo.port;
+      p.connected = true;
+      p.since = Date.now();
+      p.lastHeard = Date.now();
+      this.log(`in session with "${p.name}" (${p.address})`);
+      for (const inv of this.invites.values()) {
+        if (inv.address === p.address && inv.port === p.controlPort) {
+          p.label = inv.label;
+          inv.stage = 'connected';
+          inv.error = '';
+          clearTimeout(inv.timer);
+        }
+      }
+      this.emit('change');
+    }
+  }
+
+  onAccepted(s, rinfo, which) {
+    const inv = this.inviteFor(rinfo, s.token);
+    if (!inv) return;
+    clearTimeout(inv.timer);
+    if (which === 'control' && inv.stage === 'control') {
+      inv.stage = 'data';
+      inv.attempts = 0;
+      inv.remoteName = s.name;
+      this.sendInvite(inv);
+      return;
+    }
+    if (which === 'data' && inv.stage === 'data') {
+      const key = `out:${inv.key}`;
+      // Drop any stale record of the same remote before taking the new one.
+      for (const [k, q] of this.participants) if (q.ssrc === s.ssrc && k !== key) this.participants.delete(k);
+      const p = {
+        key, ssrc: s.ssrc, token: inv.token, name: inv.remoteName || s.name || inv.host, label: inv.label,
+        address: rinfo.address, controlPort: inv.port, dataPort: rinfo.port,
+        outbound: true, connected: true, lastSeq: -1, fedBack: -1,
+        lastHeard: Date.now(), lastSyncAnswer: Date.now(), since: Date.now(), syncs: 0,
+      };
+      this.participants.set(key, p);
+      inv.stage = 'connected';
+      inv.error = '';
+      this.log(`joined "${p.name}" at ${inv.host} (${rinfo.address}:${inv.port})`);
+      this.emit('change');
+      this.startSync(p, inv);
+    }
+  }
+
+  onRejected(s, rinfo) {
+    const inv = this.inviteFor(rinfo, s.token);
+    if (!inv) return;
+    clearTimeout(inv.timer);
+    inv.stage = 'idle';
+    inv.error = 'the session refused us — set "Who may connect" to Anyone in Audio MIDI Setup';
+    this.log(`${inv.host}: invitation refused`);
+    this.emit('change');
+    this.later(REINVITE_MS * 2, () => this.beginInvite(inv));
+  }
+
+  onBye(s, rinfo) {
+    for (const [k, p] of this.participants) {
+      if (p.ssrc === s.ssrc && p.address === rinfo.address) this.drop(k, 'left the session');
+    }
+  }
+
+  drop(key, why) {
+    const p = this.participants.get(key);
+    if (!p) return;
+    this.participants.delete(key);
+    clearInterval(p.syncTimer);
+    this.timers.delete(p.syncTimer);
+    this.log(`"${p.name}" ${why}`);
+    // If we were asked to keep this one, go and get it back.
+    for (const inv of this.invites.values()) {
+      if (inv.address === p.address && inv.port === p.controlPort && inv.stage === 'connected') {
+        inv.stage = 'idle';
+        inv.error = why;
+        this.later(p.outbound ? 1000 : REINVITE_MS, () => this.beginInvite(inv));
+      }
+    }
+    this.emit('change');
+  }
+
+  /* — clock sync — */
+
+  startSync(p) {
+    const tick = () => {
+      if (!this.participants.has(p.key)) return;
+      if (Date.now() - p.lastSyncAnswer > SYNC_TIMEOUT_MS) {
+        this.send(this.control, sessionPacket(CMD.BY, p.token, this.ssrc), p.controlPort, p.address);
+        this.drop(p.key, 'stopped answering');
+        return;
+      }
+      this.send(this.data, syncPacket(this.ssrc, 0, [this.now(), 0n, 0n]), p.dataPort, p.address);
+      p.syncs++;
+      if (p.syncs === 6) {
+        clearInterval(p.syncTimer);
+        this.timers.delete(p.syncTimer);
+        p.syncTimer = this.every(SYNC_MS, tick);
+      }
+    };
+    p.syncTimer = this.every(SYNC_FAST_MS, tick);
+    tick();
+  }
+
+  onSync(s, rinfo) {
+    const p = [...this.participants.values()].find((q) => q.ssrc === s.ssrc);
+    if (p) p.lastHeard = Date.now();
+    if (s.count === 0) {
+      this.send(this.data, syncPacket(this.ssrc, 1, [s.ts[0], this.now(), 0n]), rinfo.port, rinfo.address);
+    } else if (s.count === 1) {
+      if (p) p.lastSyncAnswer = Date.now();
+      this.send(this.data, syncPacket(this.ssrc, 2, [s.ts[0], s.ts[1], this.now()]), rinfo.port, rinfo.address);
+    }
+    // count 2 completes a sync someone else started; nothing to answer.
+  }
+
+  /** Drop inbound participants that have gone quiet (their machine slept or left without a BY). */
+  reap() {
+    const now = Date.now();
+    for (const [k, p] of this.participants) {
+      if (!p.outbound && now - (p.lastHeard || 0) > IDLE_MS) this.drop(k, 'went quiet');
+    }
+  }
+
+  sendFeedback() {
+    for (const p of this.participants.values()) {
+      if (!p.connected || p.lastSeq < 0 || p.lastSeq === p.fedBack) continue;
+      p.fedBack = p.lastSeq;
+      this.send(this.control, feedbackPacket(this.ssrc, p.lastSeq), p.controlPort, p.address);
+    }
+  }
+
+  /* — MIDI — */
+
+  onRtp(buf, rinfo) {
+    const pkt = parseRtpMidi(buf);
+    if (!pkt) return;
+    let p = [...this.participants.values()].find((q) => q.ssrc === pkt.ssrc && q.connected);
+    if (!p) {
+      // MIDI from someone not in a session with us (a stale session after our restart).
+      // Ask them to start over so the session comes back properly — once in a while, not per note.
+      const last = this.strangers.get(rinfo.address) || 0;
+      if (Date.now() - last > 5000) {
+        this.strangers.set(rinfo.address, Date.now());
+        this.send(this.control, sessionPacket(CMD.BY, 0, this.ssrc), rinfo.port - 1, rinfo.address);
+      }
+      return;
+    }
+    p.lastHeard = Date.now();
+    p.lastSeq = pkt.seq;
+    for (const m of pkt.messages) {
+      const event = describe(m);
+      if (event) this.emit('midi', { participant: p, event });
+    }
+  }
+}
+
+module.exports = {
+  Session,
+  parseRtpMidi,
+  parseSession,
+  describe,
+  sessionPacket,
+  syncPacket,
+  CMD,
+};

modules/vista-cues/server.js

@@ -0,0 +1,428 @@
+'use strict';
+
+/**
+ * Vista Cues — server part.
+ *
+ * Vista 3 cannot say what it is playing: its OSC is input-only and it sends
+ * no feedback. What it *does* have is a network MIDI session that
+ * ProPresenter and the tracks rig fire cue lists through. A session sends
+ * every message to every participant, so this module joins those sessions
+ * as one more participant (rtpmidi.js) and hears exactly what Vista hears.
+ * The admin's "Cue lists" sheet (mapping.js) turns each note into
+ * "Go on Walk-in", "Release Worship 1"…, and from those the module keeps
+ * which lists are live.
+ *
+ *   GET  /state   → { state }                     (instant paint)
+ *   GET  /stream  → SSE: `state` on every change
+ *   POST /clear   → forget which lists are live (when Vista was reset by hand)
+ *
+ * What the tile shows is what Vista was told, not what Vista confirmed: if
+ * Vista is closed or someone works the desk by hand, the two can differ.
+ */
+
+const fs = require('fs');
+const { spawn } = require('child_process');
+const { Session } = require('./rtpmidi');
+const { parseMapping, match, triggerLabel } = require('./mapping');
+
+const HEARTBEAT_MS = 15000;
+const LOG_MAX = 40;
+const DNS_SD = '/usr/bin/dns-sd';
+
+let current = null;
+
+function emptyState(extra = {}) {
+  return {
+    listening: false,
+    error: '',
+    sessionName: '',
+    port: null,
+    advertised: false,
+    sources: [],
+    current: null,
+    active: [],
+    log: [],
+    mappingErrors: [],
+    rules: 0,
+    now: Date.now(),
+    ...extra,
+  };
+}
+
+/**
+ * The wired network(s) MIDI must ride ("10.1.0.0/16, 10.2.0.0/16"). The Macs
+ * here are also on Wi-Fi and the Dante networks, and Bonjour lists each
+ * session once per network, so a sender typed or picked from the wrong copy
+ * works — until Wi-Fi hiccups mid-service. Returns [{ base, bits, text }];
+ * throws on a typo so the admin page says so at once.
+ */
+function parseNets(text) {
+  return String(text || '').split(/[\s,]+/).filter(Boolean).map((n) => {
+    const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})(?:\/(\d{1,2}))?$/.exec(n);
+    const parts = m ? m.slice(1, 5).map(Number) : [];
+    const bits = m && m[5] !== undefined ? Number(m[5]) : 32;
+    if (!m || parts.some((x) => x > 255) || bits > 32) {
+      throw new Error(`Wired network: "${n}" is not a network like 10.1.0.0/16`);
+    }
+    return { base: ipNumber(parts.join('.')), bits, text: n };
+  });
+}
+
+function ipNumber(a) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(String(a || '').trim());
+  return m ? m.slice(1, 5).reduce((n, x) => n * 256 + Number(x), 0) : null;
+}
+
+/**
+ * Why an address is not on the wired network: '' when it is (or there is no
+ * rule), 'by name' for a host name (it resolves to whichever network answers
+ * first), 'not wired' for an address outside every wired network.
+ */
+function offNetwork(nets, address) {
+  if (!nets.length || !address) return '';
+  const v = ipNumber(address);
+  if (v === null) return 'by name';
+  if (address.startsWith('127.')) return '';
+  const span = (bits) => 2 ** (32 - bits);
+  return nets.some((n) => Math.floor(v / span(n.bits)) === Math.floor(n.base / span(n.bits))) ? '' : 'not wired';
+}
+
+function endpointOf(v) {
+  const ep = v && typeof v === 'object' ? v : {};
+  return { host: String(ep.host || '').trim(), port: Number(ep.port) || 5004 };
+}
+
+module.exports = {
+  init({ config, log }) {
+    const sessionName = String(config.sessionName || '').trim() || 'ProdDash Lighting';
+    const port = Math.round(Number(config.sessionPort)) || 5040;
+    const middleC = config.middleC === 'C4' ? 'C4' : 'C3';
+    const exclusive = config.exclusive === true;
+    const headTakesOver = config.headTakesOver !== false;
+    const { rules, errors: mappingErrors, groups } = parseMapping(config.cueLists, { middleC });
+    const nets = parseNets(config.wiredNetwork);
+    const netText = nets.map((n) => n.text).join(', ');
+    if (mappingErrors.length) {
+      for (const e of mappingErrors) log(`cue lists line ${e.line} skipped (${e.why}): ${e.text}`);
+    }
+
+    const senders = [
+      { label: String(config.source1Name || '').trim() || 'ProPresenter', ...endpointOf(config.source1) },
+      { label: String(config.source2Name || '').trim() || 'Tracks', ...endpointOf(config.source2) },
+      { label: String(config.source3Name || '').trim() || 'Companion', ...endpointOf(config.source3) },
+    ].filter((s) => s.host);
+
+    const streams = new Set();
+    const lists = new Map();   // lower-cased name → { name, group, state, firedAt, lastAt, lastAction, source, trigger, goes }
+    const history = [];        // newest first
+    let currentKey = '';
+    let lastFrame = '';
+    let advertiser = null;
+    let advertised = false;
+    let stopped = false;
+
+    if (port < 1024 || port > 65534) throw new Error('Session port must be between 1024 and 65534');
+
+    const session = new Session({ name: sessionName, port, log });
+    const invites = senders.map((s) => ({ ...s, inv: null }));
+
+    /* ── what Vista was told ─────────────────────────────────────── */
+
+    function sourceLabel(p) {
+      return p.label || p.name || p.address;
+    }
+
+    function record(entry) {
+      history.unshift({ at: Date.now(), ...entry });
+      if (history.length > LOG_MAX) history.length = LOG_MAX;
+    }
+
+    function apply(rule, source, trigger) {
+      const now = Date.now();
+      const key = rule.list.toLowerCase();
+      record({ action: rule.action, list: rule.list, group: rule.group, source, trigger, mapped: true });
+      if (rule.action === 'flash') return; // a momentary hit: in the log, never live
+      if (rule.action === 'releaseAll') {
+        lists.clear();
+        currentKey = '';
+        return;
+      }
+      if (rule.action === 'release') {
+        lists.delete(key);
+        if (currentKey === key) currentKey = newestKey();
+        return;
+      }
+      let l = lists.get(key);
+      if (rule.action === 'go') {
+        // A Go replaces the other lists of its group. A Go in the first group (the
+        // main scene) takes over everything, as Vista's last-takes-precedence does;
+        // and with "Go releases others" on, every Go does.
+        const takeover = exclusive || (headTakesOver && rule.group && rule.group === groups[0]);
+        for (const [k, other] of [...lists]) {
+          if (k !== key && (takeover || (rule.group && other.group === rule.group))) lists.delete(k);
+        }
+        if (!l) {
+          l = { name: rule.list, group: rule.group, state: 'active', firedAt: now, goes: 0 };
+          lists.set(key, l);
+        }
+        l.state = 'active';
+        l.goes++;
+        l.lastAt = now;
+        l.lastAction = 'go';
+        l.source = source;
+        l.trigger = trigger;
+        currentKey = key;
+        return;
+      }
+      // pause / back act on a list that is live; on one that isn't, they only go in the log.
+      if (!l) return;
+      l.lastAt = now;
+      l.lastAction = rule.action;
+      l.source = source;
+      l.trigger = trigger;
+      if (rule.action === 'pause') l.state = 'paused'; // the next Go resumes it
+      if (rule.action === 'back') { l.state = 'active'; l.goes = Math.max(1, l.goes - 1); }
+    }
+
+    function newestKey() {
+      let best = '';
+      let at = -1;
+      for (const [k, l] of lists) if (l.lastAt > at) { best = k; at = l.lastAt; }
+      return best;
+    }
+
+    session.on('midi', ({ participant, event }) => {
+      if (event.type !== 'noteon' && event.type !== 'program') return;
+      const source = sourceLabel(participant);
+      const trigger = triggerLabel(event, middleC);
+      const rule = match(rules, event);
+      if (rule) {
+        apply(rule, source, trigger);
+        log(`${source}: ${trigger} → ${rule.action}${rule.list ? ` ${rule.list}` : ''}`);
+      } else {
+        record({ action: '', list: '', source, trigger, mapped: false });
+      }
+      broadcast();
+    });
+    session.on('change', () => broadcast());
+    // Senders are joined once our ports are ours — straight away normally,
+    // or a moment later when a busy port frees up.
+    session.on('listening', () => {
+      if (stopped) return;
+      log(`session "${sessionName}" listening on UDP ${port}/${port + 1}`);
+      for (const s of invites) s.inv = session.invite(s.host, s.port, s.label);
+      if (!advertiser) advertise();
+    });
+
+    /* ── the view-model ──────────────────────────────────────────── */
+
+    function sources() {
+      const out = [];
+      const seen = new Set();
+      for (const s of invites) {
+        const inv = s.inv;
+        const p = inv && [...session.participants.values()].find((q) => q.connected && q.address === inv.address && q.controlPort === inv.port);
+        if (p) seen.add(p.key);
+        out.push({
+          label: s.label,
+          name: p ? p.name : '',
+          address: inv?.address || s.host,
+          // A name is judged as typed: it may resolve to Wi-Fi next time even if it is wired now.
+          offNetwork: offNetwork(nets, s.host) || offNetwork(nets, inv?.address || ''),
+          host: s.host,
+          configured: true,
+          connected: Boolean(p),
+          error: p ? '' : (inv?.error || ''),
+          lastHeard: p ? p.lastHeard : null,
+        });
+      }
+      for (const p of session.participants.values()) {
+        if (seen.has(p.key) || !p.connected) continue;
+        out.push({ label: p.label || p.name, name: p.name, address: p.address, offNetwork: offNetwork(nets, p.address), configured: false, connected: true, error: '', lastHeard: p.lastHeard });
+      }
+      return out;
+    }
+
+    function groupRank(l) {
+      const i = groups.indexOf(l.group);
+      return i < 0 ? groups.length : i;
+    }
+
+    function buildState() {
+      const live = [...lists.values()].sort((a, b) => b.lastAt - a.lastAt);
+      // The headline: the live list of the sheet's first group (the scene, say,
+      // rather than whichever colour changed last); without groups, the last Go.
+      const head = groups[0];
+      const cur = (head && live.find((l) => l.group === head))
+        || (currentKey ? lists.get(currentKey) : null)
+        || null;
+      return {
+        listening: Boolean(session.control),
+        error: session.error,
+        sessionName,
+        port,
+        advertised,
+        wiredNetwork: netText,
+        sources: sources(),
+        current: cur || null,
+        // The rest in sheet order of their group, so a colour chip stays put as it changes.
+        active: live.filter((l) => l !== cur).sort((a, b) => groupRank(a) - groupRank(b) || b.lastAt - a.lastAt),
+        headline: head || '',
+        log: history,
+        mappingErrors,
+        rules: rules.length,
+        now: Date.now(),
+      };
+    }
+
+    function send(payload) {
+      for (const res of streams) {
+        try { res.write(payload); } catch { streams.delete(res); }
+      }
+    }
+
+    function broadcast() {
+      if (stopped) return;
+      const state = buildState();
+      const { now, sources: src, ...rest } = state;
+      // lastHeard moves with every packet; leave it out of change detection.
+      const frame = JSON.stringify({ ...rest, src: src.map(({ lastHeard, ...s }) => s) });
+      if (frame === lastFrame) return;
+      lastFrame = frame;
+      send(`event: state\ndata: ${JSON.stringify(state)}\n\n`);
+    }
+
+    const keepalive = setInterval(() => send(': ping\n\n'), HEARTBEAT_MS);
+    keepalive.unref?.();
+
+    /* ── being found: Bonjour on macOS ───────────────────────────── */
+
+    // Advertising _apple-midi._udp puts us in Audio MIDI Setup's Directory on
+    // every Mac here, so a sender can add us with a click. macOS ships the
+    // dns-sd tool; we run it as a child and stop it with the module. Elsewhere
+    // nothing is advertised and senders are joined by address alone.
+    function advertise() {
+      if (stopped || config.advertise === false || process.platform !== 'darwin' || !fs.existsSync(DNS_SD)) return;
+      advertiser = spawn(DNS_SD, ['-R', sessionName, '_apple-midi._udp', 'local', String(port)], { stdio: ['ignore', 'pipe', 'pipe'] });
+      advertiser.stdout.on('data', (d) => {
+        if (/Name now registered and active/i.test(String(d)) && !advertised) {
+          advertised = true;
+          log(`advertised as "${sessionName}" on port ${port}`);
+          broadcast();
+        }
+      });
+      advertiser.stderr.on('data', () => {});
+      advertiser.on('error', (e) => { log(`dns-sd: ${e.message}`); advertiser = null; });
+      advertiser.on('exit', () => {
+        advertiser = null;
+        advertised = false;
+        if (!stopped) setTimeout(advertise, 5000).unref?.();
+      });
+    }
+
+    /* ── start ───────────────────────────────────────────────────── */
+
+    session.start().then(() => broadcast());
+
+    current = {
+      streams,
+      getState: buildState,
+      clear() {
+        lists.clear();
+        currentKey = '';
+        record({ action: 'cleared', list: '', source: 'Dashboard', trigger: '', mapped: true });
+        broadcast();
+      },
+    };
+
+    return {
+      stop() {
+        stopped = true;
+        clearInterval(keepalive);
+        session.stop();
+        if (advertiser) { try { advertiser.kill(); } catch { /* gone */ } advertiser = null; }
+        for (const res of streams) { try { res.end(); } catch { /* gone */ } }
+        streams.clear();
+        if (current && current.streams === streams) current = null;
+      },
+      health() {
+        if (session.error) return { status: 'error', message: session.error };
+        const src = sources();
+        // Off the wired network: still joined (the cues keep working), but said first and in red.
+        const off = src.filter((s) => s.offNetwork);
+        if (off.length) {
+          return {
+            status: 'error',
+            message: `${off.map((s) => (s.offNetwork === 'by name'
+              ? `${s.label} is set by name (${s.host})`
+              : `${s.label} ${s.configured ? `(${s.address})` : `at ${s.address}`} is not on the wired network`)).join(' · ')}: use its address on ${netText}`,
+          };
+        }
+        const on = src.filter((s) => s.connected);
+        const lines = mappingErrors.length ? ` · ${mappingErrors.length} cue-list line${mappingErrors.length === 1 ? '' : 's'} not understood (first: line ${mappingErrors[0].line})` : '';
+        const map = rules.length ? '' : ' · no cue lists mapped yet';
+        if (on.length) {
+          const off = src.filter((s) => !s.connected).map((s) => `${s.label} (${s.error || 'joining…'})`);
+          return {
+            status: off.length ? 'connecting' : 'ok',
+            message: `In session with ${on.map((s) => s.label).join(', ')}${off.length ? ` · waiting for ${off.join(', ')}` : ''}${map}${lines}`,
+          };
+        }
+        const where = advertised ? `advertised as "${sessionName}"` : `port ${port}`;
+        if (src.length) {
+          return { status: 'connecting', message: `Joining ${src.map((s) => `${s.label}${s.error ? ` (${s.error})` : ''}`).join(', ')} · ${where}${map}${lines}` };
+        }
+        return { status: 'connecting', message: `Waiting for a MIDI session to connect · ${where}${map}${lines}` };
+      },
+    };
+  },
+
+  // For the tests.
+  _offNetwork: (text, address) => offNetwork(parseNets(text), address),
+
+  /**
+   * One picker entry, so the ＋ menu gives Vista Cues a heading of its own —
+   * a module with no list sits headless under whichever module precedes it
+   * (Slack, alphabetically). Tiles added before this keep working: they
+   * have no variant and use the module's schema.
+   */
+  tiles() {
+    return [{
+      id: 'live',
+      name: 'Live cue lists',
+      description: 'The main scene Vista is running, the FX on top, and what fired them',
+      defaultSize: { w: 5, h: 4 },
+      minSize: { w: 2, h: 1 },
+    }];
+  },
+
+  routes() {
+    const sendJson = (res, code, body) => {
+      res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+      res.end(JSON.stringify(body));
+    };
+    return {
+      'GET /state': (req, res) => sendJson(res, 200, { state: current ? current.getState() : emptyState() }),
+      '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.getState() : emptyState())}\n\n`);
+        if (!current) return void res.end();
+        try { req.socket.setKeepAlive(true, 15000); } catch { /* gone */ }
+        const set = current.streams;
+        set.add(res);
+        req.on('close', () => set.delete(res));
+      },
+      'POST /clear': (req, res) => {
+        if (!current) return sendJson(res, 503, { error: 'Vista Cues is not running' });
+        current.clear();
+        return sendJson(res, 200, { ok: true });
+      },
+    };
+  },
+};

modules/vista-cues/style.css

@@ -0,0 +1,187 @@
+/* Vista Cues. Sizes hang off the tile (container units) times the tile's
+   own text scale (--vc-scale, the title bar's − / +), so one tile reads the
+   same at 3×2 on a laptop as at 8×5 on a wall. Colours are the shell's. */
+
+[data-module="vista-cues"] .vc-root {
+  --tone: var(--text);
+  --vc-scale: 1;
+  position: absolute;
+  inset: 0;
+  container-type: size;
+  overflow: hidden;
+  color: var(--text);
+  font-variant-numeric: tabular-nums;
+  user-select: none;
+  -webkit-user-select: none;
+}
+[data-module="vista-cues"] .vc-root[data-tone="ok"] { --tone: var(--accent); }
+[data-module="vista-cues"] .vc-root[data-tone="warn"] { --tone: var(--warn); }
+[data-module="vista-cues"] .vc-root[data-tone="muted"] { --tone: var(--muted); }
+[data-module="vista-cues"] [hidden] { display: none !important; }
+
+[data-module="vista-cues"] .vc-body {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  gap: calc(clamp(3px, 2.5cqh, 14px) * var(--vc-scale));
+  padding: clamp(6px, 3.5cqmin, 22px);
+  min-width: 0;
+}
+
+[data-module="vista-cues"] .vc-offline {
+  position: absolute;
+  top: clamp(4px, 3cqmin, 14px);
+  right: clamp(6px, 3.5cqmin, 22px);
+  z-index: 2;
+  font-size: calc(clamp(9px, 4.5cqmin, 14px) * var(--vc-scale));
+  font-weight: 700;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  color: var(--danger);
+}
+[data-module="vista-cues"] .vc-root.is-offline .vc-now { opacity: 0.45; filter: grayscale(0.6); }
+
+/* ── now ── */
+
+[data-module="vista-cues"] .vc-now {
+  flex: 0 0 auto;
+  min-width: 0;
+  padding-left: clamp(6px, 2cqmin, 14px);
+  border-left: clamp(3px, 1.1cqmin, 7px) solid var(--tone);
+}
+[data-module="vista-cues"] .vc-kicker {
+  display: flex;
+  align-items: center;
+  gap: 0.6em;
+  font-size: calc(clamp(10px, 5cqmin, 18px) * var(--vc-scale));
+  color: var(--muted);
+}
+[data-module="vista-cues"] .vc-pill {
+  padding: 0.05em 0.55em;
+  border-radius: 999px;
+  font-weight: 800;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  background: var(--tone);
+  color: var(--accent-text);
+}
+[data-module="vista-cues"] .vc-root[data-tone="warn"] .vc-pill { color: var(--bg); }
+[data-module="vista-cues"] .vc-ago { font-weight: 600; }
+[data-module="vista-cues"] .vc-name-wrap { min-width: 0; }
+[data-module="vista-cues"] .vc-name {
+  font-size: calc(clamp(16px, 14cqmin, 96px) * var(--vc-scale));
+  line-height: 1.12;
+  font-weight: 800;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--text);
+}
+[data-module="vista-cues"] .vc-root[data-tone="muted"] .vc-name { color: var(--muted); font-weight: 600; }
+[data-module="vista-cues"] .vc-meta {
+  font-size: calc(clamp(10px, 4.6cqmin, 18px) * var(--vc-scale));
+  color: var(--muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+[data-module="vista-cues"] .vc-meta:empty { display: none; }
+
+/* ── other live lists ── */
+
+[data-module="vista-cues"] .vc-active {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4em;
+  flex: 0 0 auto;
+  font-size: calc(clamp(10px, 4.4cqmin, 17px) * var(--vc-scale));
+}
+[data-module="vista-cues"] .vc-chip {
+  display: inline-flex;
+  align-items: baseline;
+  gap: 0.5em;
+  max-width: 100%;
+  padding: 0.2em 0.65em;
+  border-radius: 6px;
+  border: 1px solid color-mix(in srgb, var(--accent) 45%, transparent);
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+}
+[data-module="vista-cues"] .vc-chip.is-paused {
+  border-color: color-mix(in srgb, var(--warn) 55%, transparent);
+  background: color-mix(in srgb, var(--warn) 14%, transparent);
+}
+[data-module="vista-cues"] .vc-chip-name {
+  font-weight: 700;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+[data-module="vista-cues"] .vc-chip-ago,
+[data-module="vista-cues"] .vc-chip-group { color: var(--muted); }
+[data-module="vista-cues"] .vc-chip-group { font-size: 0.8em; text-transform: uppercase; letter-spacing: 0.04em; }
+
+/* ── recent ── */
+
+[data-module="vista-cues"] .vc-recent {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: hidden;
+  font-size: calc(clamp(10px, 3.8cqmin, 15px) * var(--vc-scale));
+  border-top: 1px solid var(--border);
+  padding-top: 0.35em;
+}
+[data-module="vista-cues"] .vc-row {
+  display: grid;
+  grid-template-columns: auto 6.2em minmax(0, 1fr) auto;
+  gap: 0.8em;
+  align-items: baseline;
+  padding: 0.12em 0;
+  white-space: nowrap;
+}
+[data-module="vista-cues"] .vc-row > span { overflow: hidden; text-overflow: ellipsis; }
+[data-module="vista-cues"] .vc-row-time,
+[data-module="vista-cues"] .vc-row-source { color: var(--muted); }
+[data-module="vista-cues"] .vc-row-action { font-weight: 700; color: var(--accent); }
+[data-module="vista-cues"] .vc-row[data-action="release"] .vc-row-action,
+[data-module="vista-cues"] .vc-row[data-action="releaseAll"] .vc-row-action,
+[data-module="vista-cues"] .vc-row[data-action="cleared"] .vc-row-action { color: var(--muted); }
+[data-module="vista-cues"] .vc-row[data-action="pause"] .vc-row-action { color: var(--warn); }
+[data-module="vista-cues"] .vc-row[data-action="flash"] .vc-row-action { color: var(--text); }
+[data-module="vista-cues"] .vc-row.is-unmapped { opacity: 0.6; }
+[data-module="vista-cues"] .vc-row.is-unmapped .vc-row-action { color: var(--muted); font-weight: 500; }
+
+@container (max-width: 300px) {
+  [data-module="vista-cues"] .vc-row { grid-template-columns: 5.2em minmax(0, 1fr); }
+  [data-module="vista-cues"] .vc-row-time,
+  [data-module="vista-cues"] .vc-row-source { display: none; }
+}
+@container (max-height: 140px) {
+  [data-module="vista-cues"] .vc-recent,
+  [data-module="vista-cues"] .vc-active { display: none; }
+}
+
+/* ── senders ── */
+
+[data-module="vista-cues"] .vc-sources {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.9em;
+  margin-top: auto;
+  font-size: calc(clamp(9px, 3.4cqmin, 13px) * var(--vc-scale));
+  color: var(--muted);
+}
+[data-module="vista-cues"] .vc-src { display: inline-flex; align-items: center; gap: 0.4em; }
+[data-module="vista-cues"] .vc-dot {
+  width: 0.65em;
+  height: 0.65em;
+  border-radius: 50%;
+  background: var(--danger);
+}
+[data-module="vista-cues"] .vc-src.is-on { color: var(--text); }
+[data-module="vista-cues"] .vc-src.is-on .vc-dot { background: var(--accent); }
+[data-module="vista-cues"] .vc-src.is-off-network { color: var(--danger); }
+[data-module="vista-cues"] .vc-src.is-off-network .vc-dot { background: var(--danger); }
+@container (max-height: 140px) {
+  [data-module="vista-cues"] .vc-sources { display: none; }
+}

modules/vista-cues/vista.test.js

@@ -0,0 +1,418 @@
+'use strict';
+
+/**
+ * Tests for Vista Cues.
+ *
+ *   node modules/vista-cues/vista.test.js
+ *
+ * Plain Node, no dependencies; exits non-zero on the first failure. Covers
+ * the cue-sheet parser, RTP-MIDI packet decoding, and a real session over
+ * loopback UDP: a fake sender invites the module's session, plays notes, and
+ * the server entry's state follows.
+ */
+
+const assert = require('assert');
+const dgram = require('dgram');
+const http = require('http');
+const { parseMapping, match, noteFromName } = require('./mapping');
+const { parseRtpMidi, describe, Session } = require('./rtpmidi');
+
+let passed = 0;
+async function test(name, fn) {
+  await fn();
+  passed++;
+  console.log(`  ok  ${name}`);
+}
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+async function until(fn, ms = 3000) {
+  const end = Date.now() + ms;
+  while (Date.now() < end) {
+    if (fn()) return;
+    await wait(20);
+  }
+  throw new Error('timed out waiting');
+}
+
+/* ── a minimal independent sender ─────────────────────────────────────── */
+
+function sessionPkt(cmd, token, ssrc, name) {
+  const n = name == null ? Buffer.alloc(0) : Buffer.from(`${name}\0`);
+  const b = Buffer.alloc(16 + n.length);
+  b.writeUInt16BE(0xffff, 0);
+  b.write(cmd, 2, 'ascii');
+  b.writeUInt32BE(2, 4);
+  b.writeUInt32BE(token, 8);
+  b.writeUInt32BE(ssrc, 12);
+  n.copy(b, 16);
+  return b;
+}
+
+function rtp(ssrc, seq, midiBytes, flags = 0) {
+  const midi = Buffer.from(midiBytes);
+  const b = Buffer.alloc(13 + midi.length);
+  b[0] = 0x80;
+  b[1] = 0x61;
+  b.writeUInt16BE(seq, 2);
+  b.writeUInt32BE(1234, 4);
+  b.writeUInt32BE(ssrc, 8);
+  b[12] = flags | midi.length;
+  midi.copy(b, 13);
+  return b;
+}
+
+/** A sender that accepts invitations (like a Mac session) and can play notes. */
+async function fakeSender(port, name) {
+  const ssrc = 0x0badf00d;
+  const control = dgram.createSocket('udp4');
+  const data = dgram.createSocket('udp4');
+  const peers = [];
+  const syncs = [];
+  let seq = 100;
+  const handle = (sock, which) => (buf, r) => {
+    const cmd = buf.toString('ascii', 2, 4);
+    if (cmd === 'IN') {
+      sock.send(sessionPkt('OK', buf.readUInt32BE(8), ssrc, name), r.port, r.address);
+      if (which === 'data') peers.push({ address: r.address, port: r.port });
+    } else if (cmd === 'CK') {
+      syncs.push(buf[8]);
+      if (buf[8] === 0) {
+        const out = Buffer.from(buf);
+        out.writeUInt32BE(ssrc, 4);
+        out[8] = 1;
+        data.send(out, r.port, r.address);
+      }
+    }
+  };
+  control.on('message', handle(control, 'control'));
+  data.on('message', handle(data, 'data'));
+  await new Promise((r) => control.bind(port, '127.0.0.1', r));
+  await new Promise((r) => data.bind(port + 1, '127.0.0.1', r));
+  return {
+    peers,
+    syncs,
+    note(n, ch = 1) {
+      for (const p of peers) data.send(rtp(ssrc, seq++, [0x90 | (ch - 1), n, 100, 0x00, n, 0]), p.port, p.address);
+    },
+    close() { control.close(); data.close(); },
+  };
+}
+
+function freePort() {
+  return new Promise((resolve) => {
+    const s = dgram.createSocket('udp4');
+    s.bind(0, () => { const p = s.address().port; s.close(() => resolve(p)); });
+  });
+}
+
+/** Two adjacent free UDP ports, as a session needs. */
+async function freePair() {
+  for (let i = 0; i < 20; i++) {
+    const p = await freePort();
+    if (p > 65000) continue;
+    const ok = await new Promise((resolve) => {
+      const s = dgram.createSocket('udp4');
+      s.on('error', () => resolve(false));
+      s.bind(p + 1, () => s.close(() => resolve(true)));
+    });
+    if (ok) return p;
+  }
+  throw new Error('no free port pair');
+}
+
+(async () => {
+  console.log('mapping');
+
+  await test('reads the cue sheet forms', () => {
+    const { rules, errors } = parseMapping([
+      '# comment',
+      '60 = Walk-in',
+      'C3 - Worship 1',
+      '61 release Walk-in',
+      '62\tPause\tWorship 1',
+      '127 release all',
+      'ch2:64 = Message   # only on channel 2',
+      'pc5 = Baptism',
+      'note 66: Go: Song #2',
+      '67 = "Back Lights"',
+      'F#2 = Hazer',
+    ].join('\n'));
+    assert.deepStrictEqual(errors, []);
+    const brief = rules.map((r) => [r.channel, r.kind, r.number, r.action, r.list]);
+    assert.deepStrictEqual(brief, [
+      [null, 'note', 60, 'go', 'Walk-in'],
+      [null, 'note', 60, 'go', 'Worship 1'],
+      [null, 'note', 61, 'release', 'Walk-in'],
+      [null, 'note', 62, 'pause', 'Worship 1'],
+      [null, 'note', 127, 'releaseAll', ''],
+      [2, 'note', 64, 'go', 'Message'],
+      [null, 'program', 5, 'go', 'Baptism'],
+      [null, 'note', 66, 'go', 'Song #2'],
+      [null, 'note', 67, 'go', 'Back Lights'],
+      [null, 'note', 54, 'go', 'Hazer'],
+    ]);
+  });
+
+  await test('middle C naming', () => {
+    assert.strictEqual(noteFromName('C3', 'C3'), 60);
+    assert.strictEqual(noteFromName('C4', 'C4'), 60);
+    assert.strictEqual(noteFromName('C-2', 'C3'), 0);
+    assert.strictEqual(noteFromName('Bb3', 'C3'), 70);
+  });
+
+  await test('bad lines are reported, not fatal', () => {
+    const { rules, errors } = parseMapping('hello\n200 = Big\n61 release\nch17:3 = X\n60 = OK');
+    assert.strictEqual(rules.length, 1);
+    assert.deepStrictEqual(errors.map((e) => e.line), [1, 2, 3, 4]);
+  });
+
+  await test('groups and flashes', () => {
+    const { rules, groups, errors } = parseMapping('5 = Loose\n[Scene]\n0 = Pre Service\n8 = Message\n[Color]\n23 = Blue\n30 flash Blinder Flash 1\n[]\n9 = After');
+    assert.deepStrictEqual(errors, []);
+    assert.deepStrictEqual(groups, ['Scene', 'Color']);
+    assert.deepStrictEqual(rules.map((r) => [r.number, r.group, r.action]), [
+      [5, '', 'go'], [0, 'Scene', 'go'], [8, 'Scene', 'go'], [23, 'Color', 'go'], [30, 'Color', 'flash'], [9, '', 'go'],
+    ]);
+  });
+
+  await test('the NA cue sheet parses cleanly', () => {
+    const fs = require('fs');
+    const path = require('path');
+    const file = path.join(__dirname, '..', '..', '..', 'NA cue sheet.txt');
+    if (!fs.existsSync(file)) return;
+    const { rules, errors, groups } = parseMapping(fs.readFileSync(file, 'utf8'));
+    assert.deepStrictEqual(errors, []);
+    assert.strictEqual(rules.length, 53); // every note marked TRUE for NA in the sheet
+    assert.deepStrictEqual(groups, ['Main', 'Color', 'Blinders', 'Build', 'House', 'Lekos']);
+    assert.strictEqual(new Set(rules.map((r) => r.number)).size, rules.length);
+  });
+
+  await test('matching respects channel and kind', () => {
+    const { rules } = parseMapping('ch2:64 = Two\n64 = Any\npc64 = Program');
+    assert.strictEqual(match(rules, { type: 'noteon', channel: 2, note: 64 }).list, 'Two');
+    assert.strictEqual(match(rules, { type: 'noteon', channel: 1, note: 64 }).list, 'Any');
+    assert.strictEqual(match(rules, { type: 'program', channel: 1, program: 64 }).list, 'Program');
+    assert.strictEqual(match(rules, { type: 'noteoff', channel: 1, note: 64 }), null);
+  });
+
+  console.log('rtp-midi');
+
+  await test('note on + running-status note off', () => {
+    const p = parseRtpMidi(rtp(7, 9, [0x90, 60, 100, 0x00, 60, 0]));
+    assert.strictEqual(p.ssrc, 7);
+    assert.strictEqual(p.seq, 9);
+    assert.deepStrictEqual(p.messages.map(describe), [
+      { type: 'noteon', channel: 1, note: 60, velocity: 100 },
+      { type: 'noteoff', channel: 1, note: 60 },
+    ]);
+  });
+
+  await test('Z flag, multi-byte deltas, program change, sysex in between', () => {
+    const p = parseRtpMidi(rtp(7, 1, [0x05, 0xc2, 4, 0x81, 0x00, 0xf0, 0x7f, 0x01, 0xf7, 0x00, 0x93, 61, 9], 0x20));
+    assert.deepStrictEqual(p.messages.map(describe).filter(Boolean), [
+      { type: 'program', channel: 3, program: 4 },
+      { type: 'noteon', channel: 4, note: 61, velocity: 9 },
+    ]);
+  });
+
+  await test('journal bytes after the command section are ignored', () => {
+    const b = Buffer.concat([rtp(7, 1, [0x90, 62, 1], 0x40), Buffer.from([0x80, 0x00, 0x05, 0x01, 0x02])]);
+    assert.deepStrictEqual(parseRtpMidi(b).messages.map(describe), [{ type: 'noteon', channel: 1, note: 62, velocity: 1 }]);
+  });
+
+  console.log('session');
+
+  await test('invites a sender, keeps sync, and hears its notes', async () => {
+    const senderPort = await freePair();
+    const sender = await fakeSender(senderPort, 'Fake PP');
+    const port = await freePair();
+    const s = new Session({ name: 'Test', port });
+    assert.ok(await s.start());
+    const heard = [];
+    s.on('midi', ({ participant, event }) => heard.push([participant.label, event.type, event.note]));
+    s.invite('127.0.0.1', senderPort, 'ProPresenter');
+    await until(() => s.list().some((p) => p.connected));
+    await until(() => sender.syncs.includes(2)); // we answered its count-1 with a count-2
+    sender.note(60);
+    await until(() => heard.length >= 2);
+    assert.deepStrictEqual(heard, [['ProPresenter', 'noteon', 60], ['ProPresenter', 'noteoff', 60]]);
+    s.stop();
+    sender.close();
+    await wait(80);
+  });
+
+  await test('a config save re-inits on the same port straight away', async () => {
+    const senderPort = await freePair();
+    const sender = await fakeSender(senderPort, 'Fake PP');
+    const port = await freePair();
+    const mod = require('./server');
+    const config = { sessionPort: port, advertise: false, source1: { host: '127.0.0.1', port: senderPort } };
+    let handle = mod.init({ config, log: () => {} });
+    await until(() => handle.health().status === 'ok');
+    handle.stop();
+    handle = mod.init({ config, log: () => {} }); // what the shell does on save: stop(), then init()
+    await until(() => handle.health().status === 'ok');
+    handle.stop();
+    sender.close();
+    await wait(80);
+  });
+
+  await test('a port taken by someone else is reported, then taken once free', async () => {
+    const port = await freePair();
+    const squatter = dgram.createSocket('udp4');
+    await new Promise((r) => squatter.bind(port + 1, r));
+    const s = new Session({ name: 'Test', port });
+    let listening = false;
+    s.on('listening', () => { listening = true; });
+    assert.strictEqual(await s.start(), false);
+    assert.match(s.error, /in use/);
+    squatter.close();
+    await until(() => listening, 5000);
+    assert.strictEqual(s.error, '');
+    s.stop();
+  });
+
+  await test('server entry: notes become live cue lists, over HTTP', async () => {
+    const senderPort = await freePair();
+    const sender = await fakeSender(senderPort, 'Fake PP');
+    const port = await freePair();
+    const mod = require('./server');
+    const handle = mod.init({
+      config: {
+        sessionPort: port,
+        advertise: false,
+        source1Name: 'ProPresenter',
+        source1: { host: '127.0.0.1', port: senderPort },
+        cueLists: '60 = Walk-in\n61 = Worship 1\n70 release Walk-in\n127 release all',
+      },
+      log: () => {},
+    });
+    const routes = mod.routes({});
+    const server = http.createServer((req, res) => {
+      const r = routes[`${req.method} ${req.url}`];
+      if (r) r(req, res); else { res.writeHead(404); res.end(); }
+    });
+    await new Promise((r) => server.listen(0, '127.0.0.1', r));
+    const get = async (path, method = 'GET') => {
+      const res = await fetch(`http://127.0.0.1:${server.address().port}${path}`, { method });
+      return res.json();
+    };
+    const state = async () => (await get('/state')).state;
+
+    await until(() => sender.peers.length > 0);
+    await until(() => handle.health().status === 'ok');
+    sender.note(60);
+    await wait(100);
+    sender.note(61);
+    await wait(100);
+    let st = await state();
+    assert.strictEqual(st.current.name, 'Worship 1');
+    assert.deepStrictEqual(st.active.map((l) => l.name), ['Walk-in']);
+    assert.strictEqual(st.current.source, 'ProPresenter');
+    assert.strictEqual(st.sources[0].connected, true);
+
+    sender.note(70);
+    sender.note(99); // unmapped
+    await wait(150);
+    st = await state();
+    assert.deepStrictEqual(st.active, []);
+    assert.strictEqual(st.log[0].mapped, false);
+    assert.match(st.log[0].trigger, /Note 99/);
+
+    sender.note(127);
+    await wait(100);
+    st = await state();
+    assert.strictEqual(st.current, null);
+
+    sender.note(60);
+    await wait(100);
+    await get('/clear', 'POST');
+    st = await state();
+    assert.strictEqual(st.current, null);
+    assert.strictEqual(st.log[0].action, 'cleared');
+    handle.stop();
+
+    // Groups: a Go replaces its group's live list; the first group is the headline; flashes stay out.
+    const h2 = mod.init({
+      config: {
+        sessionPort: port, advertise: false, source1: { host: '127.0.0.1', port: senderPort },
+        cueLists: '[Scene]\n0 = Pre Service\n8 = Message\n[Color]\n22 = Red\n23 = Blue\n30 flash Blinder Flash 1',
+      },
+      log: () => {},
+    });
+    await until(() => h2.health().status === 'ok');
+    for (const n of [0, 22, 23, 30]) { sender.note(n); await wait(60); }
+    await wait(100);
+    st = await state();
+    assert.strictEqual(st.current.name, 'Pre Service');
+    assert.deepStrictEqual(st.active.map((l) => [l.group, l.name]), [['Color', 'Blue']]); // Blue replaced Red
+    assert.strictEqual(st.log[0].action, 'flash');
+    sender.note(8); // a new main scene takes over the look…
+    await wait(100);
+    st = await state();
+    assert.strictEqual(st.current.name, 'Message');
+    assert.deepStrictEqual(st.active, []);
+    sender.note(22); // …and FX fired after it layer on top again
+    await wait(100);
+    st = await state();
+    assert.deepStrictEqual(st.active.map((l) => l.name), ['Red']);
+    h2.stop();
+
+    server.close();
+    sender.close();
+    await wait(80);
+  });
+
+  await test('wired network: addresses outside it, and names, are flagged', () => {
+    const mod = require('./server');
+    const off = mod._offNetwork;
+    assert.strictEqual(off('', '10.6.9.193'), '');                          // no rule: any network
+    assert.strictEqual(off('10.1.0.0/16', '10.1.3.227'), '');
+    assert.strictEqual(off('10.1.0.0/16', '10.6.9.193'), 'not wired');      // Wi-Fi
+    assert.strictEqual(off('10.1.0.0/16', '169.254.12.3'), 'not wired');    // Dante
+    assert.strictEqual(off('10.1.0.0/16', 'NA-Tracks.local'), 'by name');
+    assert.strictEqual(off('10.1.0.0/16', '127.0.0.1'), '');                // Companion on this machine
+    assert.strictEqual(off('10.1.0.0/16, 10.6.0.0/20', '10.6.9.193'), '');  // several
+    assert.strictEqual(off('10.1.3.227', '10.1.3.227'), '');                // a single address
+    assert.throws(() => off('wifi', '10.1.3.227'), /not a network like 10\.1\.0\.0\/16/);
+    assert.throws(() => off('10.1.0.0/40', '10.1.3.227'), /not a network/);
+  });
+
+  await test('server entry: a sender off the wired network still joins, and says so', async () => {
+    const senderPort = await freePair();
+    const sender = await fakeSender(senderPort, 'Fake Tracks');
+    const port = await freePair();
+    const mod = require('./server');
+    assert.throws(() => mod.init({ config: { sessionPort: port, advertise: false, wiredNetwork: '10.1/16' }, log: () => {} }), /Wired network/);
+    const handle = mod.init({
+      config: {
+        sessionPort: port,
+        advertise: false,
+        wiredNetwork: '10.1.0.0/16',
+        source2Name: 'Tracks',
+        source2: { host: 'localhost', port: senderPort },   // a name: it may resolve to Wi-Fi next time
+        cueLists: '60 = Walk-in',
+      },
+      log: () => {},
+    });
+    await until(() => sender.peers.length > 0);                       // joined all the same
+    const h = handle.health();
+    assert.strictEqual(h.status, 'error');
+    assert.match(h.message, /^Tracks is set by name \(localhost\): use its address on 10\.1\.0\.0\/16$/);
+    const routes = mod.routes({});
+    let body = '';
+    await new Promise((r) => routes['GET /state']({}, { writeHead() {}, end(b) { body = b; r(); } }));
+    const st = JSON.parse(body).state;
+    assert.strictEqual(st.wiredNetwork, '10.1.0.0/16');
+    assert.strictEqual(st.sources[0].offNetwork, 'by name');
+    handle.stop();
+    sender.close();
+    await wait(80);
+  });
+
+  console.log(`\n${passed} passed`);
+  process.exit(0);
+})().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

tools/vista-midi-mock.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * A stand-in for the ProPresenter Mac's network MIDI session, for the Vista
+ * Cues module: an RTP-MIDI (AppleMIDI) session that accepts invitations and
+ * plays a cue sheet's notes to everyone in it, the way ProPresenter's MIDI
+ * actions reach Vista.
+ *
+ *   node tools/vista-midi-mock.js 5104             # wait to be invited on UDP 5104/5105
+ *   node tools/vista-midi-mock.js 5104 --invite 127.0.0.1:5040
+ *                                                  # …or invite ProdDash yourself
+ *   --name "Tracks Laptop"   session name (default "ProPresenter Mock")
+ *   --every 4                seconds between cues (default 4)
+ *   --channel 1              MIDI channel (default 1)
+ *   --notes 2,23,8,30        play these notes in a loop instead of the built-in sheet's
+ *
+ * Point Vista Cues' "First sender" at 127.0.0.1 port 5104 and paste the
+ * sheet this prints into "Cue lists". Kill it to watch the tile go red;
+ * start it again to watch it come back.
+ *
+ * Written separately from the module's own rtpmidi.js on purpose, so a bug
+ * there is not mirrored here.
+ */
+
+const dgram = require('dgram');
+
+const argv = process.argv.slice(2);
+const opt = (name, dflt) => {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : dflt;
+};
+const PORT = Number(argv.find((a) => /^\d+$/.test(a))) || 5104;
+const NAME = opt('name', 'ProPresenter Mock');
+const EVERY = Number(opt('every', 4)) * 1000;
+const CHANNEL = Math.min(16, Math.max(1, Number(opt('channel', 1)))) - 1;
+const INVITE = opt('invite', '');
+
+const SHEET = [
+  '60 = Walk-in',
+  '61 = Worship 1',
+  '62 = Worship 2',
+  '63 = Message',
+  '64 pause Worship 2',
+  '70 release Walk-in',
+  '71 release Worship 1',
+  '127 release all',
+];
+const NOTES = opt('notes', '');
+const SCRIPT = NOTES ? NOTES.split(',').map(Number).filter((n) => n >= 0 && n <= 127) : [60, 61, 70, 62, 64, 64, 71, 90, 63, 127];
+
+const ssrc = (Math.random() * 0xffffffff) >>> 0;
+const t0 = process.hrtime.bigint();
+const now = () => (process.hrtime.bigint() - t0) / 100000n;
+let seq = Math.floor(Math.random() * 0xffff);
+
+const peers = new Map(); // ssrc → { address, controlPort, dataPort, token, name, ready }
+
+function session(cmd, token, name) {
+  const n = name == null ? Buffer.alloc(0) : Buffer.from(`${name}\0`);
+  const b = Buffer.alloc(16 + n.length);
+  b.writeUInt16BE(0xffff, 0);
+  b.write(cmd, 2, 'ascii');
+  b.writeUInt32BE(2, 4);
+  b.writeUInt32BE(token >>> 0, 8);
+  b.writeUInt32BE(ssrc, 12);
+  n.copy(b, 16);
+  return b;
+}
+
+function ck(count, ts) {
+  const b = Buffer.alloc(36);
+  b.writeUInt16BE(0xffff, 0);
+  b.write('CK', 2, 'ascii');
+  b.writeUInt32BE(ssrc, 4);
+  b[8] = count;
+  ts.forEach((t, i) => b.writeBigUInt64BE(BigInt.asUintN(64, t), 12 + i * 8));
+  return b;
+}
+
+/** One RTP-MIDI packet: note on, then (delta 0, running status) the note off. */
+function notePacket(note) {
+  const midi = Buffer.from([0x90 | CHANNEL, note, 100, 0x00, note, 0x00]);
+  const b = Buffer.alloc(12 + 1 + midi.length);
+  b[0] = 0x80;
+  b[1] = 0x61;
+  seq = (seq + 1) & 0xffff;
+  b.writeUInt16BE(seq, 2);
+  b.writeUInt32BE(Number(now() & 0xffffffffn), 4);
+  b.writeUInt32BE(ssrc, 8);
+  b[12] = midi.length; // B=0 J=0 Z=0 P=0, LEN
+  midi.copy(b, 13);
+  return b;
+}
+
+const control = dgram.createSocket('udp4');
+const data = dgram.createSocket('udp4');
+
+function onPacket(sock, which) {
+  return (buf, r) => {
+    if (buf.length < 4 || buf.readUInt16BE(0) !== 0xffff) return;
+    const cmd = buf.toString('ascii', 2, 4);
+    if (cmd === 'IN') {
+      const token = buf.readUInt32BE(8);
+      const them = buf.readUInt32BE(12);
+      const end = buf.indexOf(0, 16);
+      const name = buf.toString('utf8', 16, end < 0 ? buf.length : end);
+      sock.send(session('OK', token, NAME), r.port, r.address);
+      const p = peers.get(them) || { address: r.address, token, name, ready: false };
+      if (which === 'control') p.controlPort = r.port;
+      else { p.dataPort = r.port; p.ready = true; console.log(`[mock] "${name}" joined from ${r.address}`); }
+      peers.set(them, p);
+    } else if (cmd === 'OK') {
+      // Our own invitation (--invite) was accepted.
+      const them = buf.readUInt32BE(12);
+      const end = buf.indexOf(0, 16);
+      const name = buf.toString('utf8', 16, end < 0 ? buf.length : end);
+      if (which === 'control') {
+        pending.stage = 'data';
+        data.send(session('IN', pending.token, NAME), pending.port + 1, pending.host);
+      } else {
+        pending.stage = 'done';
+        peers.set(them, { address: r.address, controlPort: pending.port, dataPort: r.port, token: pending.token, name, ready: true });
+        console.log(`[mock] joined "${name}" at ${r.address}:${pending.port}`);
+      }
+    } else if (cmd === 'BY') {
+      const them = buf.readUInt32BE(12);
+      if (peers.delete(them)) console.log('[mock] a participant left');
+    } else if (cmd === 'CK') {
+      const count = buf[8];
+      const ts = [buf.readBigUInt64BE(12), buf.readBigUInt64BE(20), buf.readBigUInt64BE(28)];
+      if (count === 0) data.send(ck(1, [ts[0], now(), 0n]), r.port, r.address);
+      else if (count === 1) data.send(ck(2, [ts[0], ts[1], now()]), r.port, r.address);
+    }
+  };
+}
+
+const pending = { stage: '', host: '', port: 0, token: 0 };
+
+control.on('message', onPacket(control, 'control'));
+data.on('message', onPacket(data, 'data'));
+control.bind(PORT, () => data.bind(PORT + 1, () => {
+  console.log(`[mock] session "${NAME}" on UDP ${PORT}/${PORT + 1}, channel ${CHANNEL + 1}`);
+  console.log('[mock] cue sheet for Vista Cues → Cue lists:\n  ' + SHEET.join('\n  '));
+  if (INVITE) {
+    const [host, port] = INVITE.split(':');
+    Object.assign(pending, { stage: 'control', host, port: Number(port) || 5040, token: (Math.random() * 0xffffffff) >>> 0 });
+    const tryInvite = () => {
+      if (pending.stage === 'done') return;
+      pending.stage = 'control';
+      control.send(session('IN', pending.token, NAME), pending.port, pending.host);
+      setTimeout(tryInvite, 2000);
+    };
+    tryInvite();
+  }
+}));
+
+// Clock sync, as the session that started it would do (harmless otherwise).
+setInterval(() => {
+  for (const p of peers.values()) if (p.ready) data.send(ck(0, [now(), 0n, 0n]), p.dataPort, p.address);
+}, 10000);
+
+let step = 0;
+setInterval(() => {
+  const ready = [...peers.values()].filter((p) => p.ready);
+  if (!ready.length) return;
+  const note = SCRIPT[step % SCRIPT.length];
+  step += 1;
+  const pkt = notePacket(note);
+  for (const p of ready) data.send(pkt, p.dataPort, p.address);
+  console.log(`[mock] note ${note} → ${ready.length} participant${ready.length === 1 ? '' : 's'}`);
+}, EVERY);
+
+process.on('SIGINT', () => {
+  for (const p of peers.values()) control.send(session('BY', p.token), p.controlPort, p.address);
+  setTimeout(() => process.exit(0), 100);
+});