Merge pull request 'Release builds: Intel disk images, a Windows bundle, and where to download them' (#24) from claude/release-builds into main

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

.gitignore

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

CLAUDE.md

@@ -3,7 +3,8 @@
 Modular production dashboard web app for Waters Church, developed in this repo.
 The app lives at the repo root and is built: zero-dependency Node server
 (`server.js`, Node 18+), dashboard shell client in `public/`, admin page at
-`/admin`, modules in `modules/`, and a native macOS menu-bar launcher in
+`/admin`, modules in `modules/` (the repo's copies — a packaged install ships
+none and installs them from the admin page's catalog), and a native macOS menu-bar launcher in
 `launcher/macos/` (Swift, no dependencies — the shipped macOS app: it carries
 the server and its own Node runtime, supervises them, and owns the macOS
 permissions modules declare; see its README). Runtime state (module
@@ -28,7 +29,12 @@ title-bar controls). The rules that matter most:
   ship inside the module folder** (zero deps is the norm). **Everything the
   module does runs inside its server entry** — no helper scripts, companion
   programs or daemons the operator starts by hand; a listener or decoder is
-  started in `init()` and stopped in `stop()`. Declare `"proddash": ">=x.y.z"`
+  started in `init()` and stopped in `stop()`. **A native helper ships
+  prebuilt inside the module folder for Apple silicon macOS and 64-bit
+  Windows** (`bin/<name>-macos-arm64`, `bin/<name>-win-x64.exe`, source and
+  build script under `native/`); nothing is ever compiled on the machine
+  running ProdDash, and a missing binary means the feature reports itself
+  off, not a broken module. Declare `"proddash": ">=x.y.z"`
   and bump the module's `version` on every change.
 - Browsers never call upstream services directly; the module's server routes
   proxy everything (no CORS, secrets stay server-side).

README.md

@@ -30,11 +30,23 @@ and a clear degraded state, then recover on their own.
 
 ## Run it
 
+Ready-made builds are on the
+[Releases page](http://chronicles-ab.waterschurch.org:3000/michael/ProdDash/releases);
+the files themselves live in
+[ProdDash-releases](http://chronicles-ab.waterschurch.org:3000/michael/ProdDash-releases).
+There is a disk image for Apple silicon Macs, one for Intel Macs, and a
+bundle for 64-bit Windows. Every build updates itself afterwards from the
+admin page, so the download only has to be recent, not current.
+
 ### macOS — the app
 
-Open the disk image and drag **ProdDash** to Applications. That's the whole
+Download the disk image for your Mac — `ProdDash-<version>-arm64.dmg` for
+Apple silicon, `ProdDash-<version>-x86_64.dmg` for Intel — open it and drag
+**ProdDash** to Applications. That's the whole
 installation: the app carries the dashboard and its own Node runtime, so
-nothing else has to be installed and nothing can be missing. It lives in the
+nothing else has to be installed. It carries no modules — open **Admin →
+Available modules**, tick the ones this machine needs and press **Install
+selected**; each updates on its own from then on. It lives in the
 menu bar, starts and stops the server, can open at login, and holds the
 permissions the modules need — the microphone the LTC listener reads, and
 local network access for ProdCom and ProPresenter. macOS grants those to the
@@ -43,12 +55,26 @@ a launchd job) simply doesn't have them, and an LTC input goes silently to
 zeroes.
 
 Build the disk image from a checkout with
-[launcher/macos](launcher/macos)/`build.sh`:
+[launcher/macos](launcher/macos)/`build.sh` (`ARCH=x86_64` in front of it
+for Intel):
 
 ```bash
 cd launcher/macos && ./build.sh --dmg
 ```
 
+### Windows — the bundle
+
+Download `ProdDash-<version>-win-x64.zip`, unzip it somewhere you can write
+to — `C:\ProdDash`, say, not Program Files, because updates write into the
+folder — and double-click **ProdDash.bat**. The window it opens is the
+dashboard running: it stays open, and it starts the server again when the
+admin page applies an update. Allow `node.exe` on private networks when the
+firewall asks, so other screens can reach it. Settings and layouts live in
+`%APPDATA%\ProdDash`, so a new bundle never loses them. To start with
+Windows, put a shortcut to `ProdDash.bat` in `shell:startup`. There is no
+menu-bar-style launcher for Windows yet; the bundle is built with
+[launcher/windows](launcher/windows)/`build.sh`.
+
 ### Anywhere else, or from a checkout
 
 Requires [Node.js](https://nodejs.org) 18 or newer.
@@ -179,13 +205,15 @@ below. Nothing is installed without someone clicking.
 - **Available modules** lists modules in the repo that aren't installed
   here. **Install** downloads the module into the data directory's `modules/`
   and starts it right away — nothing is written into the app folder, and no
-  restart is needed. Modules that ship with your copy of ProdDash are
+  restart is needed. Tick several and press **Install selected** to fetch
-  "bundled"; ones you installed are "installed"; if both exist, the newer
+  them in one go. A packaged ProdDash (the app, the Windows bundle) ships
-  version runs.
+  with no modules at all: this list is how every one of them arrives, and a
+  ProdDash update never brings one along. A git checkout also runs the
+  modules in its own tree ("bundled"); if both exist, the newer version runs.
 - **Uninstall** on a module card removes an installed module's files. For a
-  bundled module (its folder belongs to the app) it hides the module from
+  checkout's bundled module (its folder belongs to the repo) it hides the
-  every dashboard instead; it reappears under Available modules and can be
+  module from every dashboard instead; it reappears under Available modules
-  brought back without downloading. Settings are kept either way.
+  and can be brought back without downloading. Settings are kept either way.
 - **Module updates**: when the repo has a newer version of an installed
   module, its card shows **Update to vX**.
 - **Version requirements**: every module declares the ProdDash versions it
@@ -303,9 +331,11 @@ below. Nothing is installed without someone clicking.
   status, NOW and NEXT labels, slide count, progress bar, the next list and
   its item tags, plus tidy titles.
 - **Timers** — live ProPresenter timers (countdown, countdown-to-time,
-  elapsed) and LTC timecode as auto-sized cards. The ＋ picker lists every
+  elapsed), the **video countdown** (time left on what ProPresenter is
-  discovered timer (and the LTC card) as its own tile, or add "All timers"
+  playing, with a per-tile "Looping videos" switch so looping backgrounds
-  and pick a selection via the tile's "Timers ▾" menu; overruns are
+  stay hidden) and LTC timecode as auto-sized cards. The ＋ picker lists
+  every discovered timer (and the LTC card) as its own tile, or add "All
+  timers" and pick a selection via the tile's "Timers ▾" menu; overruns are
   unmistakably red. Read-only — no start/stop controls. Admin config is in
   three groups: **ProPresenter** (endpoint host : port, API password),
   **LTC Timecode** (the listener switch, and — when it's on — the audio
@@ -323,8 +353,9 @@ below. Nothing is installed without someone clicking.
   session (Start ProdDash.command) and approve the one-time prompt; a server
   started over SSH or by bare launchd silently captures zeros. (Engine
   self-test: `node modules/propresenter-timers/ltc.selftest.js`.)
-- **PCO Plan** — Planning Center Services, as two tiles in the ＋ picker:
+- **PCO Plan** — Planning Center Services, as three tiles in the ＋ picker:
-  **Plan** (the order of service) and **Teams** (who is scheduled).
+  **Plan** (the order of service), **Teams** (who is scheduled) and **Song
+  Key** (the key of the item on screen).
 
   **Plan** shows every
   plan item with its scheduled start time, length, type, song key,
@@ -346,6 +377,25 @@ below. Nothing is installed without someone clicking.
   `{series} • {part} | {serviceType} • {date}`), colors, text size, and a
   show/hide checklist for every detail.
 
+  With an **AbleSet** module installed and configured, the Plan tile also
+  follows the band: while AbleSet plays a song that is the item on screen,
+  that item's background fills as the song goes, and its sections slide past
+  in a strip at the bottom right of the item, the one playing filling in
+  turn. Both are switches in the tile's gear (**Song progress**, **Song
+  sections**), and both are simply absent when there is no AbleSet module, it
+  is switched off, or it has no host — nothing to turn off and nothing to
+  explain.
+
+  **Song Key** is one value, as large as the tile allows: the key of the item
+  ProPresenter has live, with the song's name and the next key under it — both
+  switches, as is the colour. When the feed that picks the item is gone the key
+  stays up, faded, and the tile's dot says so rather than pretending to be
+  current.
+
+  Keys are written as notes wherever the module shows one: Planning Center's
+  `Bb` and `F#m` read as B♭ and F♯m, on the Plan tile's item badge and in the
+  Song Key tile alike.
+
   **Teams** shows the same plan's team and position assignments — each team
   as a band of its people, with their photo (fetched through ProdDash, never
   by the browser; initials when Planning Center has none) and a dot for

docs/MODULE-GUIDE.md

@@ -28,7 +28,10 @@ people running the booth depend on them.
    ProdDash. If your feature needs a listener, a decoder or a worker, your
    server entry owns it: start it in `init()`, stop it in `stop()`, report
    it in `health()`. A child process the module itself spawns and supervises
-   is fine; a program someone launches by hand is not.
+   is fine; a program someone launches by hand is not. **A native helper —
+   anything that is not JavaScript — ships prebuilt inside the module folder,
+   for Apple silicon macOS and 64-bit Windows; nothing is ever compiled on
+   the machine running ProdDash** (see "Native helpers" below).
 4. **Declare the ProdDash version you need** (`"proddash": ">=1.1.0"` in the
    manifest) and **bump your own `version`** whenever you change the module.
    The admin page refuses to install a module whose requirement the running
@@ -83,19 +86,86 @@ modules/<id>/
 ├── module.json      manifest (required)
 ├── client.js        ES module, client entry (required)
 ├── server.js        server entry (optional — only if you need server code)
+├── bin/             native helpers, prebuilt per platform (only if you need one)
+│   ├── <name>-macos-arm64
+│   └── <name>-win-x64.exe
+├── native/          their source and the script that builds every bin/ file
 └── ... assets       (css, images…) served statically at /modules/<id>/
 ```
 
 **Installation is exactly this:** in the admin page, open **Available
 modules** and press **Install** — the module is downloaded from the ProdDash
 repo into the server's data directory (`<data dir>/modules/<id>/`) and starts
-immediately. Developing locally? Drop the folder into `modules/` (bundled
+immediately. A packaged ProdDash — the macOS app, the Windows bundle — ships
-with the checkout) or into the data directory's `modules/` and restart. No
+with **no modules at all**: every one of them arrives this way, and the
-shell code changes, ever. Modules bundled with a checkout and modules
+shell's own update never brings one along, so what is in git is exactly what
-installed from the admin page live side by side; when both have the same id
+runs on a booth. Developing locally? A git checkout runs whatever is in its
-the newer version runs. **Uninstall** in the admin page removes an installed
+own `modules/` folder (the repo's copies, "bundled"), or drop a folder into
-module's files (a bundled one is hidden instead, since its folder belongs to
+the data directory's `modules/` and restart. No shell code changes, ever. In
-the app); its settings are kept for a later reinstall.
+a checkout the two live side by side; when both have the same id the newer
+version runs. **Uninstall** in the admin page removes an installed module's
+files (in a checkout, the tree's copy is hidden instead, since that folder
+belongs to the repo); its settings are kept for a later reinstall.
+
+### Native helpers
+
+Some features need a program JavaScript cannot be: reading an audio input,
+decoding timecode, measuring sound. Rule 3 says the module owns that program;
+this section says how it ships: **already built, for every platform it runs
+on, inside the module folder.** The machine running ProdDash is a packaged
+app or the Windows bundle plus modules from the admin page's catalog. It has
+no compiler and never will — the catalog delivers exactly the folder that is
+in the repo, so the binaries live in git next to the code.
+
+- **Platforms.** Apple silicon macOS and 64-bit Windows are required. Intel
+  macOS is welcome but optional. One file per platform in `bin/`, named for
+  what it is:
+
+  | Platform | File |
+  | --- | --- |
+  | macOS, Apple silicon | `bin/<name>-macos-arm64` |
+  | Windows, 64-bit | `bin/<name>-win-x64.exe` |
+  | macOS, Intel (optional) | `bin/<name>-macos-x86_64` |
+
+- **Pick it at runtime, and cope without it.** Choose by `process.platform`
+  and `process.arch`; when there is no file for this machine, the feature
+  says so — in `health()` and in the tile's `setStatus` — and everything else
+  in the module keeps working. Never try to build it, never look for a copy
+  elsewhere on the machine, never tell the operator to install anything.
+
+  ```js
+  const HELPERS = {
+    darwin: { arm64: 'ltc-capture-macos-arm64', x64: 'ltc-capture-macos-x86_64' },
+    win32: { x64: 'ltc-capture-win-x64.exe' },
+  };
+  const name = HELPERS[process.platform]?.[process.arch];
+  const helper = name ? path.join(__dirname, 'bin', name) : '';
+  if (!helper || !fs.existsSync(helper)) {
+    // Timecode is off on this platform. Say it once, keep the clock running.
+  }
+  ```
+
+- **One contract, any language.** Every platform's binary speaks the same
+  command line and output format, so `server.js` has one code path. What is
+  behind it is your choice per platform — Swift against CoreAudio on macOS,
+  C#, C or Rust on Windows — the module does not care.
+- **Source and build beside it.** Keep the source under `native/` with one
+  script that produces every `bin/` file from a checkout, so any binary can be
+  rebuilt from what is committed. A helper that cannot be rebuilt does not
+  ship.
+- **Bump the module version whenever a binary changes**, like any other
+  file — that is how installs learn about it.
+- **Keep them lean.** Optimised builds, no debug symbols, a few megabytes at
+  most: the catalog fetches the whole repo as one archive, capped at 80 MB.
+- **Signing.** Apple silicon refuses unsigned code, so sign the macOS binary
+  — Developer ID when you have it, ad-hoc at least. Windows needs nothing:
+  files the app writes carry no download mark, so SmartScreen never sees
+  them. Permissions come from the launcher (see "Permissions macOS has to
+  grant"), not from the binary.
+
+A helper that ends up existing for one platform only is an exception made
+on purpose, not a default: say so in the module's README and in the health
+line, so a Windows booth knows why the feature is off.
 
 ## module.json
 

launcher/macos/README.md

@@ -51,6 +51,7 @@ the cycle rather than spinning forever.
 ```bash
 ./build.sh                 # build/ProdDash.app — the whole application
 ./build.sh --dmg           # …and build/ProdDash-<version>-arm64.dmg
+ARCH=x86_64 ./build.sh --dmg   # the same for Intel Macs (…-x86_64.dmg)
 ./build.sh --install       # …and copy it to /Applications
 ./build.sh --run           # …and open it
 ./build.sh --notarize      # with --dmg: notarise and staple (Developer ID)
@@ -68,9 +69,10 @@ Builds for **Apple Silicon**. To change that, or to move to a newer Node, edit
 against nodejs.org's published checksums either way.
 
 The app icon is built from `public/icons/icon-512.png`, so ProdDash's own icon
-is the app's icon. A module's native helper is compiled during the build
+is the app's icon. The app carries no modules: they are installed from the
-(`<name>.swift` beside a module's files becomes `<name>`), so the Mac running
+admin page's catalog into the data directory, and a module's native helper
-ProdDash never needs a compiler.
+ships prebuilt inside it (see the module guide), so the Mac running ProdDash
+never needs a compiler.
 
 ## Signing
 

launcher/macos/build.sh

@@ -1,6 +1,8 @@
 #!/bin/zsh
 # Build ProdDash.app — the whole application: launcher, server and its own
-# Node runtime, with nothing to install first.
+# Node runtime, with nothing to install first. It carries no modules: those
+# come from the admin page's catalog into the data directory, and a module's
+# native helper ships prebuilt inside it (docs/MODULE-GUIDE.md).
 #
 #   ./build.sh                 build/ProdDash.app, self-contained
 #   ./build.sh --dmg           …and build/ProdDash-<version>-arm64.dmg
@@ -11,6 +13,8 @@
 #   ./build.sh --dev           launcher only — no Node, no server payload, so
 #                              it runs against the checkout. Seconds, not
 #                              minutes, while working on the launcher itself.
+#   ARCH=x86_64 ./build.sh     the same for Intel Macs (default: arm64, Apple
+#                              silicon); the Node it embeds follows.
 #
 # Signing: a "Developer ID Application" certificate is used when one is
 # installed (override with CODESIGN_IDENTITY). Without one the app is signed
@@ -27,8 +31,13 @@ LAUNCHER_VERSION="1.0.0"
 # The Node the app ships. Bump it here; the download is checksum-verified
 # against nodejs.org's own SHASUMS256.txt and cached in .cache/.
 NODE_VERSION="v24.21.0"
-ARCH="arm64"
+ARCH="${ARCH:-arm64}"   # arm64 (Apple silicon) or x86_64 (Intel)
 DEPLOYMENT_TARGET="13.0"
+case "$ARCH" in
+  arm64) NODE_ARCH="arm64" ;;
+  x86_64) NODE_ARCH="x64" ;;   # nodejs.org's name for it
+  *) echo "build.sh: ARCH must be arm64 or x86_64, not $ARCH" >&2; exit 2 ;;
+esac
 
 REPO_ROOT="../.."
 OUT_DIR="build"
@@ -106,7 +115,7 @@ fi
 
 # ── the server, and the Node that runs it ────────────────────────────────
 if [[ $DEV -eq 0 ]]; then
-  TARBALL="node-$NODE_VERSION-darwin-$ARCH.tar.gz"
+  TARBALL="node-$NODE_VERSION-darwin-$NODE_ARCH.tar.gz"
   mkdir -p "$CACHE_DIR"
   if [[ ! -f "$CACHE_DIR/$TARBALL" ]]; then
     echo "  fetching Node $NODE_VERSION (~50 MB, cached for next time)"
@@ -125,25 +134,16 @@ if [[ $DEV -eq 0 ]]; then
   echo "  embedding Node $NODE_VERSION"
   mkdir -p "$CONTENTS/Resources/node/bin"
   tar -xzf "$CACHE_DIR/$TARBALL" -C "$CONTENTS/Resources/node/bin" --strip-components 2 \
-    "node-$NODE_VERSION-darwin-$ARCH/bin/node"
+    "node-$NODE_VERSION-darwin-$NODE_ARCH/bin/node"
 
-  echo "  embedding ProdDash $VERSION"
+  echo "  embedding ProdDash $VERSION (no modules — the catalog installs them)"
   mkdir -p "$PAYLOAD/config"
   cp "$REPO_ROOT/server.js" "$REPO_ROOT/package.json" "$PAYLOAD/"
-  cp -R "$REPO_ROOT/public" "$REPO_ROOT/modules" "$PAYLOAD/"
+  cp -R "$REPO_ROOT/public" "$PAYLOAD/"
   # Only the checked-in defaults: config/ also holds this machine's own
   # modules.json and layouts when ProdDash has ever run from the checkout.
   cp "$REPO_ROOT/config/proddash.json" "$PAYLOAD/config/"
   find "$PAYLOAD" -name '.DS_Store' -delete
-
-  # A module's native helper is built here, so the Mac running ProdDash needs
-  # no compiler: <name>.swift beside a module's files becomes <name>.
-  for source in "$PAYLOAD"/modules/*/*.swift; do
-    [[ -e "$source" ]] || continue
-    helper="${source%.swift}"
-    echo "  compiling $(basename "$(dirname "$source")")/$(basename "$helper")"
-    swiftc -O -target "$ARCH-apple-macos$DEPLOYMENT_TARGET" -o "$helper" "$source"
-  done
 fi
 
 # ── signing ──────────────────────────────────────────────────────────────
@@ -165,16 +165,6 @@ fi
 if [[ -f "$CONTENTS/Resources/node/bin/node" ]]; then
   codesign "${SIGN[@]}" --entitlements Resources/node.entitlements "$CONTENTS/Resources/node/bin/node"
 fi
-if [[ $DEV -eq 0 ]]; then
-  for helper in "$PAYLOAD"/modules/*/*; do
-    # A compiled helper is the extensionless executable beside a module's
-    # sources — test the name, not the path, which has dots all over it.
-    name=$(basename "$helper")
-    [[ -f "$helper" && -x "$helper" && "$name" != *.* ]] || continue
-    echo "  signing $name"
-    codesign "${SIGN[@]}" --entitlements Resources/helper.entitlements "$helper"
-  done
-fi
 codesign "${SIGN[@]}" --entitlements Resources/ProdDash.entitlements --identifier "$BUNDLE_ID" "$APP"
 codesign --verify --deep --strict "$APP" && echo "  signature verifies"
 

launcher/windows/build.sh

@@ -0,0 +1,121 @@
+#!/bin/zsh
+# Build the Windows bundle — ProdDash-<version>-win-x64.zip: the dashboard,
+# its own Node runtime and a start script, so nothing has to be installed on
+# the Windows machine. Unzip, double-click ProdDash.bat, done. It carries no
+# modules: those come from the admin page's catalog into %APPDATA%\ProdDash.
+#
+#   ./build.sh                 build/ProdDash-<version>-win-x64.zip
+#
+# Builds on macOS or Linux (zsh, curl, shasum, unzip, zip). Node for Windows
+# comes from nodejs.org, checksum-verified against its SHASUMS256.txt and
+# cached in .cache/. There is no Windows launcher app yet: ProdDash.bat keeps
+# the server running and starts it again when the admin page applies an
+# update (the server exits with code 75 to ask for that).
+set -e -u
+cd "$(dirname "$0")"
+
+APP_NAME="ProdDash"
+# The Node the bundle ships — keep in step with launcher/macos/build.sh.
+NODE_VERSION="v24.21.0"
+NODE_DIST="node-$NODE_VERSION-win-x64"
+
+REPO_ROOT="../.."
+OUT_DIR="build"
+CACHE_DIR=".cache"
+
+for tool in curl shasum unzip zip; do
+  command -v "$tool" >/dev/null || { echo "build.sh: $tool not found" >&2; exit 1; }
+done
+
+VERSION=$(sed -n 's/.*"version" *: *"\([^"]*\)".*/\1/p' "$REPO_ROOT/package.json" | head -1)
+[[ -n "$VERSION" ]] || { echo "build.sh: can't read the version from package.json" >&2; exit 1; }
+NAME="$APP_NAME-$VERSION-win-x64"
+STAGE="$OUT_DIR/$NAME"
+
+echo "ProdDash $VERSION — building the Windows bundle"
+rm -rf "$OUT_DIR"
+mkdir -p "$STAGE/node" "$STAGE/config" "$CACHE_DIR"
+
+# ── Node for Windows ─────────────────────────────────────────────────────
+ZIPFILE="$NODE_DIST.zip"
+if [[ ! -f "$CACHE_DIR/$ZIPFILE" ]]; then
+  echo "  fetching Node $NODE_VERSION for Windows (~30 MB, cached for next time)"
+  curl -fsSL --retry 3 -o "$CACHE_DIR/$ZIPFILE.part" "https://nodejs.org/dist/$NODE_VERSION/$ZIPFILE"
+  mv "$CACHE_DIR/$ZIPFILE.part" "$CACHE_DIR/$ZIPFILE"
+fi
+SUMS="$CACHE_DIR/SHASUMS256-$NODE_VERSION.txt"
+[[ -f "$SUMS" ]] || curl -fsSL --retry 3 -o "$SUMS" "https://nodejs.org/dist/$NODE_VERSION/SHASUMS256.txt"
+# This binary ships under ProdDash's name — check it every build.
+WANT=$(awk -v f="$ZIPFILE" '$2 == f {print $1}' "$SUMS")
+GOT=$(shasum -a 256 "$CACHE_DIR/$ZIPFILE" | awk '{print $1}')
+if [[ -z "$WANT" || "$WANT" != "$GOT" ]]; then
+  echo "build.sh: $ZIPFILE does not match nodejs.org's checksum — refusing to ship it" >&2
+  exit 1
+fi
+echo "  embedding Node $NODE_VERSION (node.exe and its licence)"
+unzip -q -j "$CACHE_DIR/$ZIPFILE" "$NODE_DIST/node.exe" "$NODE_DIST/LICENSE" -d "$STAGE/node"
+
+# ── ProdDash ─────────────────────────────────────────────────────────────
+echo "  embedding ProdDash $VERSION (no modules — the catalog installs them)"
+cp "$REPO_ROOT/server.js" "$REPO_ROOT/package.json" "$STAGE/"
+cp -R "$REPO_ROOT/public" "$STAGE/"
+# Only the checked-in defaults: config/ also holds this machine's own
+# modules.json and layouts when ProdDash has ever run from the checkout.
+cp "$REPO_ROOT/config/proddash.json" "$STAGE/config/"
+find "$STAGE" -name '.DS_Store' -delete
+
+# ── the start script and the read-me, with Windows line endings ──────────
+crlf() { awk '{ printf "%s\r\n", $0 }' > "$1"; }
+
+crlf "$STAGE/ProdDash.bat" <<'BAT'
+@echo off
+rem ProdDash - double-click to start. Keep this window open: closing it stops the dashboard.
+title ProdDash
+cd /d "%~dp0"
+rem The server exits with code 75 after applying an update from the admin page; start it again.
+set PRODDASH_LAUNCHER=1
+:run
+"%~dp0node\node.exe" server.js
+set CODE=%ERRORLEVEL%
+if %CODE% EQU 75 goto run
+echo.
+echo ProdDash stopped (exit code %CODE%). Press any key to close this window.
+pause >nul
+BAT
+
+crlf "$STAGE/README.txt" <<README
+ProdDash $VERSION for Windows (64-bit)
+=======================================
+
+Nothing to install. This folder holds the dashboard and its own copy of Node.
+
+1. Move this folder somewhere you can write to, for example C:\ProdDash
+   (not Program Files: updates write into this folder).
+2. Double-click ProdDash.bat. A window opens and stays open while the
+   dashboard runs; closing it stops the dashboard.
+   - If Windows warns about the file, choose More info, then Run anyway.
+   - When Windows Defender Firewall asks about node.exe, allow it on
+     private networks so other screens can reach the dashboard.
+3. Open http://localhost:24500 on this PC. Other devices on the network use
+   http://<this PC's IP address>:24500. Settings are on the admin page,
+   http://localhost:24500/admin.
+4. The bundle ships without modules. On the admin page, tick the ones this
+   PC needs under Available modules and press Install selected; each one
+   updates on its own from then on.
+
+Your settings and layouts live in %APPDATA%\ProdDash, not in this folder,
+so unzipping a new version or updating never loses them.
+
+Start with Windows: press Win+R, type shell:startup, press Enter, and put a
+shortcut to ProdDash.bat in the folder that opens.
+
+Updates: the admin page's Update now fetches the new version into this
+folder and restarts the dashboard; the window stays open. A copy of the
+version it replaced is kept for a short while in case the new one will not
+start.
+README
+
+# ── zip ──────────────────────────────────────────────────────────────────
+echo "  zipping"
+(cd "$OUT_DIR" && zip -q -r -X "$NAME.zip" "$NAME")
+echo "built $OUT_DIR/$NAME.zip ($(du -sh "$OUT_DIR/$NAME.zip" | awk '{print $1}'))"

modules/pco-plan/client.js

@@ -1,8 +1,8 @@
 /* PCO Plan — client part.
 
-   The module presents two tiles and this is the entry for both: the Teams
+   The module presents three tiles and this is the entry for all of them: the
-   tile (picker entry "teams") is built by teams-client.js, everything below
+   Teams tile (picker entry "teams") is built by teams-client.js and the Song
-   draws the Plan tile.
+   Key tile ("key") by key-client.js; everything below draws the Plan tile.
 
    The server part reads Planning Center and (optionally) follows the
    ProPresenter module's live item; this tile only renders the plan it is
@@ -13,6 +13,8 @@
    the connection settings. */
 
 import createTeams from "./teams-client.js";
+import createKey from "./key-client.js";
+import { prettyKey } from "./key-notation.js";
 
 const REFRESH_SVG = '<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 12a9 9 0 1 1-2.64-6.36"/><path d="M21 3v6h-6"/></svg>';
 
@@ -21,8 +23,9 @@ const MINUS_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" st
 const PLUS_SVG = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" aria-hidden="true"><path d="M12 5v14M5 12h14"/></svg>';
 
 export default function create({ root, moduleApi }) {
-  // Tiles added as "Teams" carry that variant and have their own settings.
+  // Each picker entry carries its variant and its own settings.
   if (moduleApi.variant === "teams") return createTeams({ root, moduleApi });
+  if (moduleApi.variant === "key") return createKey({ root, moduleApi });
   return createPlan({ root, moduleApi });
 }
 
@@ -34,6 +37,7 @@ function createPlan({ root, moduleApi }) {
   let ticker = null;
   let lastCurrentId = null;
   let lastListKey = '';
+  let absView = null;         // what the server says AbleSet is doing, if anything
   let userScrolledAt = 0;
 
   root.innerHTML = `
@@ -366,7 +370,8 @@ function createPlan({ root, moduleApi }) {
       if (on('showKey') && item.keyName) {
         const key = document.createElement('span');
         key.className = 'pp-key';
-        key.textContent = item.keyName;
+        // B♭, F♯m — the same notation the Song Key tile uses.
+        key.textContent = prettyKey(item.keyName);
         titleLine.appendChild(key);
       }
       if (on('showNowIndicator')) {
@@ -493,6 +498,133 @@ function createPlan({ root, moduleApi }) {
     renderLiveMarks();
   }
 
+  /* ── AbleSet: the song playing under the current item ──────────────
+     Everything here draws only when the server says there is an AbleSet
+     module, it is configured and reachable, and the song it is playing is
+     the plan item on screen. Any of those missing and the tile looks
+     exactly as it did before AbleSet existed. */
+
+  /** The playhead now, in beats, carried forward from the last packet. */
+  function absBeatsNow() {
+    if (!absView || absView.beats == null) return null;
+    if (!absView.playing || !absView.tempo) return absView.beats;
+    const since = Math.max(0, serverNow() - absView.at) / 1000;
+    return absView.beats + since * (absView.tempo / 60);
+  }
+
+  function absFraction(part) {
+    const beats = absBeatsNow();
+    if (beats == null || !part || part.start == null || part.end == null) return null;
+    const span = part.end - part.start;
+    if (!(span > 0)) return null;
+    return Math.max(0, Math.min(1, (beats - part.start) / span));
+  }
+
+  /** The row AbleSet's song belongs to — only ever the current one. */
+  function absRow() {
+    const a = absView;
+    if (!a || !a.available || !a.reachable || !a.song || !a.itemId) return null;
+    if (a.itemId !== lastCurrentId) return null;
+    return listEl.querySelector(`.pp-row[data-id="${CSS.escape(a.itemId)}"]`) || null;
+  }
+
+  /** Keep the playing section visible in the strip — this strip, nothing else. */
+  function absScrollSections(strip) {
+    const active = strip.querySelector('.pp-abs-sec.is-now');
+    if (!active) return;
+    const box = strip.getBoundingClientRect();
+    const rect = active.getBoundingClientRect();
+    const delta = (rect.left - box.left) - (strip.clientWidth - rect.width) / 2;
+    if (Math.abs(delta) < 1) return;
+    strip.scrollTo({ left: strip.scrollLeft + delta, behavior: 'smooth' });
+  }
+
+  function renderAbleSet() {
+    const row = absRow();
+
+    // Anything left on a row that is no longer the one goes.
+    for (const stale of listEl.querySelectorAll('.pp-fill, .pp-abs-sections')) {
+      if (!row || !row.contains(stale)) stale.remove();
+    }
+    if (!row) return;
+
+    if (on('absProgress')) {
+      const fraction = absFraction(absView.song);
+      if (fraction == null) {
+        row.querySelector('.pp-fill')?.remove();
+      } else {
+        let fill = row.querySelector('.pp-fill');
+        if (!fill) {
+          fill = document.createElement('div');
+          fill.className = 'pp-fill';
+          row.prepend(fill); // behind the row's content, which the stylesheet lifts
+        }
+        fill.style.width = `${(fraction * 100).toFixed(2)}%`;
+      }
+    } else {
+      row.querySelector('.pp-fill')?.remove();
+    }
+
+    if (on('absSections') && absView.sections.length) {
+      const main = row.querySelector('.pp-col-main');
+      let strip = row.querySelector('.pp-abs-sections');
+      if (!strip && main) {
+        strip = document.createElement('div');
+        strip.className = 'pp-abs-sections';
+        main.appendChild(strip);
+      }
+      if (strip) {
+        // The chips are rebuilt only when the song's sections change. Moving
+        // on to the next section just moves the classes: rebuilding would
+        // throw the strip's scroll away thirteen times a song.
+        const key = absView.sections.map((s) => s.name).join('\u0000');
+        if (strip.dataset.key !== key) {
+          strip.dataset.key = key;
+          strip.dataset.now = '';
+          strip.innerHTML = '';
+          for (const section of absView.sections) {
+            const chip = document.createElement('span');
+            chip.className = 'pp-abs-sec';
+            chip.textContent = section.name;
+            strip.appendChild(chip);
+          }
+        }
+        const now = absView.section?.index ?? -1;
+        if (strip.dataset.now !== String(now)) {
+          strip.dataset.now = String(now);
+          [...strip.children].forEach((chip, i) => {
+            chip.classList.toggle('is-now', i === now);
+            chip.classList.toggle('is-done', i < now);
+            if (i !== now) chip.style.removeProperty('--pp-sec-fill');
+          });
+          requestAnimationFrame(() => absScrollSections(strip));
+        }
+        const active = strip.children[now];
+        if (active) {
+          const fraction = absFraction(absView.section);
+          active.style.setProperty('--pp-sec-fill', fraction == null ? '0%' : `${(fraction * 100).toFixed(1)}%`);
+        }
+      }
+    } else {
+      row.querySelector('.pp-abs-sections')?.remove();
+    }
+  }
+
+  /**
+   * Centre a row in this tile's own list. `scrollIntoView` would walk up and
+   * scroll every ancestor that can scroll with it, which on a dashboard taller
+   * than the window drags the whole board; moving `listEl.scrollTop` moves
+   * this tile and nothing else. Measured from rectangles rather than
+   * `offsetTop` because the rows' offset parent is the tile, not the list.
+   */
+  function keepInView(row) {
+    const list = listEl.getBoundingClientRect();
+    const rect = row.getBoundingClientRect();
+    const delta = (rect.top - list.top) - (listEl.clientHeight - rect.height) / 2;
+    if (Math.abs(delta) < 1) return;
+    listEl.scrollTo({ top: listEl.scrollTop + delta, behavior: 'smooth' });
+  }
+
   /** Current / done classes and the elapsed timers, without rebuilding rows. */
   function renderLiveMarks() {
     const live = state?.live || {};
@@ -531,11 +663,12 @@ function createPlan({ root, moduleApi }) {
       }
       if (!h.endedAt) elapsedEl.classList.add('is-running');
     }
+    renderAbleSet();
     if (currentId !== lastCurrentId) {
       lastCurrentId = currentId;
       if (currentId && tilePrefs().autoScroll !== false && Date.now() - userScrolledAt > 8000) {
         const row = listEl.querySelector(`.pp-row[data-id="${CSS.escape(currentId)}"]`);
-        row?.scrollIntoView({ block: 'center', behavior: 'smooth' });
+        if (row) keepInView(row);
       }
     }
   }
@@ -610,6 +743,7 @@ function createPlan({ root, moduleApi }) {
   }
 
   function tick() {
+    renderAbleSet();
     if (!state?.plan) return;
     renderClock();
     if (state.live?.following && on('showItemRuntime')) renderLiveMarks();
@@ -621,6 +755,7 @@ function createPlan({ root, moduleApi }) {
     if (!payload || typeof payload !== 'object' || !payload.state) return;
     state = payload.state;
     if (Number.isFinite(payload.now)) skew = payload.now - Date.now();
+    if (payload.ableset) absView = payload.ableset;
     feedOffline = false;
     render();
   }
@@ -641,6 +776,16 @@ function createPlan({ root, moduleApi }) {
             accept(JSON.parse(ev.data));
           } catch { /* a bad frame is not fatal */ }
         },
+        // Its own event, several a second while a song plays: redraw that one
+        // row rather than the whole list.
+        ableset(ev) {
+          try {
+            absView = JSON.parse(ev.data);
+          } catch {
+            return;
+          }
+          if (state) renderAbleSet();
+        },
       },
     });
   }

modules/pco-plan/key-client.js

@@ -0,0 +1,181 @@
+/* PCO Plan — the Song Key tile.
+
+   One thing, big: the key of the plan item on screen. It reads the same
+   streamed state the Plan tile does, so it needs no connection of its own;
+   which item is current comes from the ProPresenter module, as ever. */
+
+import { parseKey, prettyKey } from "./key-notation.js";
+
+export default function createKey({ root, moduleApi }) {
+  let state = null;
+  let stream = null;
+  let feedOffline = false;
+
+  root.innerHTML = `
+    <div class="pk-wrap">
+      <div class="pk-key"></div>
+      <div class="pk-name"></div>
+      <div class="pk-next"></div>
+    </div>`;
+
+  const wrap = root.querySelector('.pk-wrap');
+  const keyEl = root.querySelector('.pk-key');
+  const nameEl = root.querySelector('.pk-name');
+  const nextEl = root.querySelector('.pk-next');
+
+  const cfg = () => moduleApi.instanceSettings || {};
+  const on = (key) => cfg()[key] !== false; // unset = shown
+
+  /* ── the item on screen, and the one after it ───────────────────── */
+
+  function items() {
+    return Array.isArray(state?.items) ? state.items : [];
+  }
+
+  function currentItem() {
+    const id = state?.live?.following ? state.live.currentItemId : '';
+    return id ? items().find((it) => it.id === id) || null : null;
+  }
+
+  /** The next item that actually has a key — a talk between two songs is skipped. */
+  function nextKeyed(after) {
+    const list = items();
+    const from = after ? list.findIndex((it) => it.id === after.id) + 1 : 0;
+    if (from <= 0) return null;
+    for (let i = from; i < list.length; i += 1) {
+      if (list[i].keyName) return list[i];
+    }
+    return null;
+  }
+
+  function titleOf(item) {
+    return item ? (item.song?.title || item.title || '') : '';
+  }
+
+  /* ── render ─────────────────────────────────────────────────────── */
+
+  function renderStatus() {
+    if (feedOffline) return moduleApi.setStatus('error', 'ProdDash server unreachable — reconnecting…');
+    if (!state) return moduleApi.setStatus('connecting', 'Connecting…');
+    if (!state.configured) return moduleApi.setStatus('error', 'No Planning Center credentials — add them in Admin');
+    if (!state.serviceTypeSet) return moduleApi.setStatus('error', 'No service type selected — pick one in Admin');
+    if (!state.reachable) {
+      return moduleApi.setStatus(state.lastFetched ? 'error' : 'connecting', state.lastError || 'Reading the plan…');
+    }
+    const item = currentItem();
+    if (!state.live?.following) return moduleApi.setStatus('ok', 'Not following ProPresenter — no item is current');
+    // The key on screen stays — the band still needs it — but a tile must
+    // never look confidently live while the feed that chose it is gone.
+    if (!state.live.available) {
+      return moduleApi.setStatus('error', `${state.live.reason || 'ProPresenter feed unavailable'} — showing the last item`);
+    }
+    if (!state.live.ppReachable) return moduleApi.setStatus('error', 'ProPresenter unreachable — showing the last item');
+    if (!item) return moduleApi.setStatus('ok', 'Waiting for an item to go live');
+    moduleApi.setStatus('ok', `${titleOf(item)}${item.keyName ? ` — ${prettyKey(item.keyName)}` : ' — no key in the plan'}`);
+  }
+
+  /**
+   * A key is a note, so it is worth setting properly: "Bb" and "F#m" read
+   * better with the accidental raised and the minor kept small.
+   */
+  function drawKey(text) {
+    keyEl.innerHTML = '';
+    const parts = parseKey(text);
+    if (!parts) {
+      keyEl.textContent = text;
+      return;
+    }
+    keyEl.appendChild(document.createTextNode(parts.note));
+    if (parts.accidental) {
+      const acc = document.createElement('span');
+      acc.className = 'pk-accidental';
+      acc.textContent = parts.accidental;
+      keyEl.appendChild(acc);
+    }
+    if (parts.quality) {
+      const tail = document.createElement('span');
+      tail.className = 'pk-quality';
+      tail.textContent = parts.quality;
+      keyEl.appendChild(tail);
+    }
+  }
+
+  function render() {
+    wrap.classList.toggle('is-offline', feedOffline);
+    const live = state?.live;
+    wrap.classList.toggle('is-stale', Boolean(live?.following && (!live.available || !live.ppReachable)));
+    const color = String(cfg().keyColor || '').trim();
+    wrap.style.setProperty('--pk-color', /^[#a-zA-Z0-9(),.%\s-]+$/.test(color) && color ? color : '#4ea1ff');
+    renderStatus();
+
+    const item = currentItem();
+    const key = item?.keyName || '';
+    wrap.classList.toggle('has-key', Boolean(key));
+
+    if (!state || !state.configured || !state.serviceTypeSet) {
+      drawKey('—');
+      nameEl.textContent = state ? 'Set up PCO Plan in Admin' : 'Connecting…';
+      nextEl.textContent = '';
+      return;
+    }
+    if (!item) {
+      drawKey('—');
+      nameEl.textContent = state.live?.following ? 'Nothing live' : 'Not following ProPresenter';
+      nextEl.textContent = '';
+      return;
+    }
+
+    drawKey(key || '—');
+    nameEl.textContent = on('showSongName') ? titleOf(item) : '';
+    nameEl.hidden = !nameEl.textContent;
+
+    const next = on('showNextKey') ? nextKeyed(item) : null;
+    nextEl.textContent = next ? `Next: ${prettyKey(next.keyName)} · ${titleOf(next)}` : '';
+    nextEl.hidden = !nextEl.textContent;
+  }
+
+  /* ── live feed ──────────────────────────────────────────────────── */
+
+  function accept(payload) {
+    if (!payload || typeof payload !== 'object' || !payload.state) return;
+    state = payload.state;
+    feedOffline = false;
+    render();
+  }
+
+  function connect() {
+    stream = moduleApi.sse('/stream', {
+      open() { feedOffline = false; render(); },
+      error() { feedOffline = true; render(); },
+      events: {
+        state(ev) {
+          try {
+            accept(JSON.parse(ev.data));
+          } catch { /* a bad frame is not fatal */ }
+        },
+      },
+    });
+  }
+
+  /* ── lifecycle ──────────────────────────────────────────────────── */
+
+  return {
+    start() {
+      moduleApi.setStatus('connecting', 'Connecting…');
+      moduleApi.fetch('/state')
+        .then((res) => (res.ok ? res.json() : null))
+        .then((body) => { if (body && !state) accept(body); })
+        .catch(() => { /* the stream will cover it */ });
+      connect();
+      render();
+    },
+    stop() {
+      stream?.close();
+      stream = null;
+      root.innerHTML = '';
+    },
+    onConfigChange() {
+      // Admin holds the connection only; the server re-inits and re-sends.
+    },
+  };
+}

modules/pco-plan/key-notation.js

@@ -0,0 +1,25 @@
+/* PCO Plan — how a song key is written.
+
+   Planning Center stores keys as typed: "Bb", "F#m", "Ab". Every tile in this
+   module shows them as notes instead — B♭, F♯m, A♭ — so the plan, the badge
+   on an item and the Song Key tile all agree. Shared rather than repeated
+   because the day one of them changes, they all should. */
+
+/** "F#m" → { note: 'F', accidental: '♯', quality: 'm' }; anything odd → null. */
+export function parseKey(raw) {
+  const match = /^([A-G])\s*([#b♯♭]?)\s*(.*)$/.exec(String(raw || '').trim());
+  if (!match) return null;
+  const [, note, accidental, quality] = match;
+  return {
+    note,
+    accidental: accidental === '#' ? '♯' : accidental === 'b' ? '♭' : accidental,
+    quality: quality.trim(),
+  };
+}
+
+/** The same thing as one string, for a badge or a caption. */
+export function prettyKey(raw) {
+  const parts = parseKey(raw);
+  if (!parts) return String(raw || '').trim();
+  return `${parts.note}${parts.accidental}${parts.quality}`;
+}

modules/pco-plan/module.json

@@ -1,9 +1,9 @@
 {
   "id": "pco-plan",
   "name": "PCO Plan",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "proddash": ">=1.4.0",
-  "description": "Order of service and team assignments from Planning Center Services",
+  "description": "Order of service, team assignments and the song key from Planning Center Services",
   "provides": [
     "timers"
   ],
@@ -382,6 +382,18 @@
       "label": "Match line",
       "default": true,
       "group": "Show"
+    },
+    "absProgress": {
+      "type": "boolean",
+      "label": "Song progress",
+      "default": true,
+      "group": "Show"
+    },
+    "absSections": {
+      "type": "boolean",
+      "label": "Song sections",
+      "default": true,
+      "group": "Show"
     }
   },
   "tiles": [
@@ -609,6 +621,36 @@
           "columns": 2
         }
       }
+    },
+    {
+      "id": "key",
+      "name": "Song Key",
+      "description": "The key of the item on screen, big",
+      "defaultSize": {
+        "w": 2,
+        "h": 2
+      },
+      "minSize": {
+        "w": 1,
+        "h": 1
+      },
+      "instanceSchema": {
+        "keyColor": {
+          "type": "color",
+          "label": "Key",
+          "default": "#4ea1ff"
+        },
+        "showSongName": {
+          "type": "boolean",
+          "label": "Song name",
+          "default": true
+        },
+        "showNextKey": {
+          "type": "boolean",
+          "label": "Next key",
+          "default": true
+        }
+      }
     }
   ]
 }

modules/pco-plan/server.js

@@ -9,6 +9,10 @@
  *
  *   GET  /state    → { state, now }        (instant paint for new tiles)
  *   GET  /stream   → SSE, `state` events   (change-detected, heartbeated)
+ *                    plus `ableset` events: the song AbleSet is playing, its
+ *                    sections and playhead, when there is an AbleSet module
+ *                    to follow (see below). Its own event so the playhead
+ *                    never drags the plan onto the wire with it.
  *   POST /refresh  → re-read the plan now
  *   GET  /service-types → { options } for the admin "Service type" select,
  *                         grouped by Planning Center folder path
@@ -33,6 +37,13 @@
  *   GET /service_types/{st}/item_note_categories       (note category names)
  *   GET …/plans/{id}/team_members?include=team,person  (who is scheduled)
  *
+ * Following AbleSet: the same loopback trick, entirely optional. When this
+ * ProdDash has an AbleSet module that is configured and answering, its song,
+ * sections and playhead are passed to the tiles, and the song is matched to a
+ * plan item by name so a tile can fill that item as the song plays. With no
+ * such module — not installed, disabled, no host — tiles are told
+ * `available: false` and draw none of it.
+ *
  * Following ProPresenter: instead of talking to ProPresenter a second time,
  * this module reads the propresenter-now-next module's own SSE feed over
  * loopback (/api/modules/propresenter-now-next/stream, on shell.port) and
@@ -59,7 +70,7 @@ const http = require('http');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { placeDocument, messageItemOf, playlistMirrorsPlan } = require('./matching');
+const { placeDocument, messageItemOf, playlistMirrorsPlan, similarity, MATCH_THRESHOLD } = require('./matching');
 const {
   MINUTE,
   serviceTimes,
@@ -85,6 +96,12 @@ const HEARTBEAT_MS = 15000;
 /** The Now/Next module whose feed we follow. */
 const NOW_NEXT_ID = 'propresenter-now-next';
 const NOW_NEXT_RETRY_MS = 3000;
+/** The AbleSet module, followed the same way — entirely optional (see below). */
+const ABLESET_ID = 'ableset';
+const ABLESET_RETRY_MS = 3000;
+const ABLESET_MISSING_RETRY_MS = 15000;
+/** Fastest the playhead is passed on; AbleSet offers more than a tile can draw. */
+const ABLESET_POS_MS = 200;
 const NOW_NEXT_MISSING_RETRY_MS = 15000;
 /** How many distinct documents seen live are remembered for the admin selects. */
 const SEEN_DOCUMENTS_MAX = 200;
@@ -153,6 +170,28 @@ function clearedLive() {
   };
 }
 
+/**
+ * What tiles are told about AbleSet. `available` false covers every way there
+ * may be nothing to draw — no module installed, disabled, or not answering —
+ * and the tiles then show none of it at all.
+ */
+function clearedAbleSet() {
+  return {
+    available: false,
+    configured: false,
+    reachable: false,
+    reason: '',
+    playing: false,
+    tempo: null,
+    song: null,
+    section: null,
+    sections: [],
+    beats: null,
+    itemId: '',
+    at: 0,
+  };
+}
+
 /** The service that owns the clock, as tiles and the timers see it. */
 function clearedService() {
   return {
@@ -1258,6 +1297,170 @@ module.exports = {
     const badPorts = new Set();
 
     /** Fallback only: a browser reached us on this Host — normally the shell's real port. */
+
+    /* — AbleSet, over loopback like the ProPresenter feed above — */
+
+    /**
+     * The AbleSet module, if this ProdDash has one. Nothing here is required:
+     * a dashboard with no AbleSet module, a disabled one, or one with no host
+     * configured simply reports `available: false` and the tiles draw none of
+     * it. Installing AbleSet later lights it up without a restart, because a
+     * 404 is retried on the slow timer like any other missing feed.
+     *
+     * What tiles get is deliberately small — the song, its sections, and the
+     * playhead in beats with a stamp — because it moves five times a second
+     * and must never drag the plan (items, teams) onto the wire with it. It
+     * rides its own `ableset` event on the module's one stream.
+     */
+    let absRequest = null;
+    let absRetryTimer = null;
+    let absPosTimer = null;
+    let absLastSent = 0;
+    let absLastStill = '';
+    let abs = clearedAbleSet();
+
+    function absPart(p) {
+      if (!p || typeof p !== 'object') return null;
+      const name = String(p.name || '').trim();
+      if (!name) return null;
+      const n = (v) => (Number.isFinite(Number(v)) ? Number(v) : null);
+      return { name, index: n(p.index), start: n(p.start), end: n(p.end) };
+    }
+
+    /**
+     * Which plan item AbleSet's song is, by the same name matching the live
+     * ProPresenter document uses. Without this a progress bar would happily
+     * fill the sermon while the band rehearses the next song: the tile only
+     * draws progress when the song AbleSet is playing IS the item on screen.
+     */
+    function absItemFor(songName) {
+      if (!songName) return '';
+      let best = null;
+      for (const item of state.items) {
+        if (item.itemType === 'header') continue;
+        const score = Math.max(
+          similarity(songName, item.title),
+          item.song ? similarity(songName, item.song.title) : 0
+        );
+        if (score >= MATCH_THRESHOLD && (!best || score > best.score)) best = { id: item.id, score };
+      }
+      return best ? best.id : '';
+    }
+
+    function applyAbleSet(view) {
+      const song = absPart(view?.song);
+      abs = {
+        available: true,
+        configured: Boolean(view?.configured),
+        reachable: Boolean(view?.reachable),
+        playing: Boolean(view?.playing),
+        tempo: Number.isFinite(Number(view?.tempo)) ? Number(view.tempo) : null,
+        song,
+        section: absPart(view?.section),
+        sections: Array.isArray(view?.sections)
+          ? view.sections.slice(0, 60).map((s) => ({ name: String(s?.name || ''), color: s?.color || null }))
+          : [],
+        beats: Number.isFinite(Number(view?.pos?.beats)) ? Number(view.pos.beats) : null,
+        itemId: song ? absItemFor(song.name) : '',
+        at: Date.now(),
+      };
+      broadcastAbleSet();
+    }
+
+    /** Only the playhead moved: keep everything else and restamp. */
+    function applyAbleSetPos(pos) {
+      if (!abs.available) return;
+      abs = {
+        ...abs,
+        beats: Number.isFinite(Number(pos?.beats)) ? Number(pos.beats) : abs.beats,
+        at: Date.now(),
+      };
+      broadcastAbleSet();
+    }
+
+    /**
+     * Fan the slice out. A change in anything but the playhead goes at once;
+     * the playhead itself is throttled, since AbleSet offers more packets
+     * than any tile can draw.
+     */
+    function broadcastAbleSet(force) {
+      const { beats, at, ...still } = abs;
+      const frame = JSON.stringify(still);
+      const changed = frame !== absLastStill;
+      absLastStill = frame;
+      const now = Date.now();
+      if (!force && !changed && now - absLastSent < ABLESET_POS_MS) {
+        // Due soon anyway — make sure the last packet of a burst still lands.
+        if (!absPosTimer) {
+          absPosTimer = setTimeout(() => { absPosTimer = null; broadcastAbleSet(true); }, ABLESET_POS_MS);
+          absPosTimer.unref?.();
+        }
+        return;
+      }
+      clearTimeout(absPosTimer);
+      absPosTimer = null;
+      absLastSent = now;
+      if (!streams.size) return;
+      writeAll(streams, `event: ableset\ndata: ${JSON.stringify(abs)}\n\n`);
+    }
+
+    function absUnavailable(reason, retryMs) {
+      if (abs.available || abs.reason !== reason) {
+        abs = { ...clearedAbleSet(), reason };
+        broadcastAbleSet(true);
+      }
+      if (stopped) return;
+      clearTimeout(absRetryTimer);
+      absRetryTimer = setTimeout(connectAbleSet, retryMs);
+      absRetryTimer.unref?.();
+    }
+
+    function connectAbleSet() {
+      if (stopped) return;
+      const port = nnPort;
+      const req = http.get(
+        { host: '127.0.0.1', port, path: `/api/modules/${ABLESET_ID}/stream`, headers: { Accept: 'text/event-stream' } },
+        (res) => {
+          if (res.statusCode !== 200) {
+            res.resume();
+            return absUnavailable(
+              res.statusCode === 404 ? 'no AbleSet module here' : `AbleSet module feed answered ${res.statusCode}`,
+              ABLESET_MISSING_RETRY_MS
+            );
+          }
+          res.setEncoding('utf8');
+          let buffer = '';
+          res.on('data', (chunk) => {
+            buffer += chunk;
+            let idx;
+            while ((idx = buffer.indexOf('\n\n')) >= 0) {
+              const block = buffer.slice(0, idx);
+              buffer = buffer.slice(idx + 2);
+              let event = 'message';
+              let data = '';
+              for (const line of block.split('\n')) {
+                if (line.startsWith('event:')) event = line.slice(6).trim();
+                else if (line.startsWith('data:')) data += line.slice(5).trim();
+              }
+              if (!data) continue;
+              try {
+                if (event === 'state') applyAbleSet(JSON.parse(data).state ?? JSON.parse(data));
+                else if (event === 'pos') applyAbleSetPos(JSON.parse(data));
+              } catch { /* a bad frame is not fatal */ }
+            }
+          });
+          res.on('end', () => absUnavailable('AbleSet module feed ended', ABLESET_RETRY_MS));
+          res.on('error', () => absUnavailable('AbleSet module feed dropped', ABLESET_RETRY_MS));
+        }
+      );
+      req.on('error', (err) => {
+        if (req !== absRequest) return; // superseded by a reconnect on the learned port
+        absUnavailable(`ProdDash loopback failed: ${err.message}`, ABLESET_RETRY_MS);
+      });
+      req.setTimeout(45000, () => req.destroy(new Error('feed went silent')));
+      absRequest = req;
+    }
+
     function learnPort(hostHeader) {
       if (shellPort) return; // the shell told us; nothing to learn
       const port = portFromHost(hostHeader);
@@ -1269,6 +1472,10 @@ module.exports = {
       try { nnRequest?.destroy(); } catch { /* gone */ }
       nnRequest = null;
       connectNowNext();
+      clearTimeout(absRetryTimer);
+      try { absRequest?.destroy(); } catch { /* gone */ }
+      absRequest = null;
+      connectAbleSet();
     }
 
     /**
@@ -1527,6 +1734,9 @@ module.exports = {
       state.live.reason = 'Connecting to the ProPresenter module feed';
       connectNowNext();
     }
+    // Always: whether there is an AbleSet module to follow is its answer, not
+    // an admin setting here.
+    connectAbleSet();
     mirrorService();
 
     const heartbeat = setInterval(() => {
@@ -1559,6 +1769,7 @@ module.exports = {
       timerStreams,
       pco,
       getState: () => state,
+      getAbleSet: () => abs,
       learnPort,
       refresh() {
         clearTimeout(pollTimer);
@@ -1580,7 +1791,10 @@ module.exports = {
         clearInterval(ticker);
         clearTimeout(pollTimer);
         clearTimeout(nnRetryTimer);
+        clearTimeout(absRetryTimer);
+        clearTimeout(absPosTimer);
         try { nnRequest?.destroy(); } catch { /* gone */ }
+        try { absRequest?.destroy(); } catch { /* gone */ }
         for (const set of [streams, timerStreams]) {
           for (const res of set) {
             try { res.end(); } catch { /* already gone */ }
@@ -1622,7 +1836,11 @@ module.exports = {
     return {
       'GET /state': (req, res) => {
         current?.learnPort(req.headers.host);
-        json(res, 200, { state: current ? current.getState() : clearedState(), now: Date.now() });
+        json(res, 200, {
+          state: current ? current.getState() : clearedState(),
+          ableset: current ? current.getAbleSet() : clearedAbleSet(),
+          now: Date.now(),
+        });
       },
 
       'GET /stream': (req, res) => {
@@ -1630,6 +1848,7 @@ module.exports = {
         sseHead(res);
         const state = current ? current.getState() : clearedState();
         res.write(`event: state\ndata: ${JSON.stringify({ state, now: Date.now() })}\n\n`);
+        res.write(`event: ableset\ndata: ${JSON.stringify(current ? current.getAbleSet() : clearedAbleSet())}\n\n`);
         if (!current) return void res.end();
         const { streams } = current;
         try { req.socket.setKeepAlive(true, 15000); } catch { /* gone */ }

modules/pco-plan/style.css

@@ -86,6 +86,7 @@
 }
 
 [data-module="pco-plan"] .pp-row {
+  position: relative;
   display: flex;
   align-items: flex-start;
   gap: 0.6em;
@@ -205,7 +206,9 @@
 
 [data-module="pco-plan"] .pp-now-tag {
   display: none;
-  padding: 0.05em 0.45em;
+  /* Optically centred like the section chips: uppercase has no descenders,
+     so the capitals sat 0.59px low in the pill. */
+  padding: 0.018em 0.45em 0.082em;
   border-radius: 999px;
   background: var(--pp-current);
   color: var(--bg);
@@ -589,3 +592,155 @@
 
 [data-module="pco-plan"] .tm-wrap.is-offline .tm-head { border-bottom-color: color-mix(in srgb, var(--danger) 50%, transparent); }
 [data-module="pco-plan"] .tm-wrap.is-offline .tm-body { opacity: 0.6; }
+
+
+/* ── AbleSet under the current item ───────────────────────────────────
+   Drawn only while an AbleSet module is configured, reachable, and playing
+   the song this item is. The fill is a layer behind the row's own content;
+   everything else in the row is lifted over it. */
+
+[data-module="pco-plan"] .pp-fill {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 0;
+  width: 0;
+  border-radius: 0.5em 0 0 0.5em;
+  background: color-mix(in srgb, var(--pp-current) 26%, transparent);
+  /* Packets arrive about five times a second; the glide covers the gaps. */
+  transition: width 0.22s linear;
+  pointer-events: none;
+}
+[data-module="pco-plan"] .pp-row > *:not(.pp-fill) { position: relative; z-index: 1; }
+
+/* The sections strip, bottom right of the current item. */
+[data-module="pco-plan"] .pp-abs-sections {
+  display: flex;
+  gap: 0.3em;
+  /* Bottom right of the item: hug the content and sit against the right edge
+     until there are more sections than fit, when it fills the width and
+     scrolls instead. */
+  width: fit-content;
+  max-width: 100%;
+  margin-top: 0.35em;
+  margin-left: auto;
+  padding-bottom: 0.1em;
+  overflow-x: auto;
+  overflow-y: hidden;
+  scrollbar-width: none;
+  overscroll-behavior: contain;
+  -webkit-mask-image: linear-gradient(90deg, transparent, #000 1.2em, #000 calc(100% - 1.2em), transparent);
+  mask-image: linear-gradient(90deg, transparent, #000 1.2em, #000 calc(100% - 1.2em), transparent);
+}
+[data-module="pco-plan"] .pp-abs-sections::-webkit-scrollbar { display: none; }
+
+[data-module="pco-plan"] .pp-abs-sec {
+  flex: none;
+  /* Uppercase text has no descenders, so the font's descent allowance below
+     the baseline leaves the caps sitting high in the box — measured at 0.9px
+     too much headroom. The padding is a touch shallower on top and deeper
+     below to centre the letters themselves; in em, so it holds at any text
+     size. */
+  padding: 0.095em 0.55em 0.185em;
+  /* The same rounded square, tinted ground and transparent border the AbleSet
+     module gives its own section pills, so the two read as one family. */
+  border-radius: 0.35em;
+  border: 1px solid transparent;
+  background: color-mix(in srgb, var(--text) 8%, var(--panel));
+  font-size: 0.72em;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  white-space: nowrap;
+  color: var(--muted);
+  transition: color 0.2s ease, border-color 0.2s ease, background 0.2s ease;
+}
+[data-module="pco-plan"] .pp-abs-sec.is-done { opacity: 0.45; }
+
+/* The section now playing fills left to right as it goes, like the row. */
+/* The section playing keeps its own ground and fills across it, so the
+   progress reads against the chip rather than against the row behind it. */
+[data-module="pco-plan"] .pp-abs-sec.is-now {
+  color: var(--text);
+  border-color: color-mix(in srgb, var(--pp-current) 60%, transparent);
+  background:
+    linear-gradient(90deg,
+      color-mix(in srgb, var(--pp-current) 45%, var(--panel)) var(--pp-sec-fill, 0%),
+      color-mix(in srgb, var(--text) 8%, var(--panel)) var(--pp-sec-fill, 0%));
+}
+
+/* ── the Song Key tile ────────────────────────────────────────────────
+   One value, as large as the tile allows. Sizes come from the tile itself
+   (container units), like the AbleSet module's single readouts, so a small
+   tile and a wall-sized one both read properly. */
+
+[data-module="pco-plan"] .pk-wrap {
+  --pk-color: #4ea1ff;
+  position: absolute;
+  inset: 0;
+  container-type: size;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0.2em;
+  padding: 4%;
+  text-align: center;
+  user-select: none;
+}
+
+[data-module="pco-plan"] .pk-key {
+  font-size: clamp(18px, 46cqmin, 260px);
+  font-weight: 800;
+  line-height: 1;
+  letter-spacing: -0.01em;
+  color: var(--muted);
+  white-space: nowrap;
+}
+[data-module="pco-plan"] .pk-wrap.has-key .pk-key { color: var(--pk-color); }
+
+/* A key is a note, but it has to read as one word at a glance from the back
+   of a room: the accidental and the quality sit on the same line as the
+   letter, only smaller. Raising the accidental looked like two stacked
+   characters at tile sizes. */
+[data-module="pco-plan"] .pk-accidental {
+  font-size: 0.68em;
+  margin-left: 0.01em;
+}
+[data-module="pco-plan"] .pk-quality {
+  font-size: 0.5em;
+  font-weight: 700;
+  margin-left: 0.05em;
+  opacity: 0.85;
+}
+
+[data-module="pco-plan"] .pk-name {
+  max-width: 100%;
+  font-size: clamp(9px, 9cqmin, 30px);
+  font-weight: 600;
+  line-height: 1.2;
+  color: var(--text);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+[data-module="pco-plan"] .pk-name[hidden] { display: none; }
+
+[data-module="pco-plan"] .pk-next {
+  max-width: 100%;
+  font-size: clamp(8px, 6.5cqmin, 20px);
+  font-weight: 600;
+  color: var(--muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+[data-module="pco-plan"] .pk-next[hidden] { display: none; }
+
+[data-module="pco-plan"] .pk-wrap.is-offline { opacity: 0.6; }
+/* The feed that picks the item is gone: the key stays readable, but faded,
+   so nobody trusts it as current without looking at the status dot. */
+[data-module="pco-plan"] .pk-wrap.is-stale .pk-key { opacity: 0.55; }
+[data-module="pco-plan"] .pk-wrap.is-stale .pk-name,
+[data-module="pco-plan"] .pk-wrap.is-stale .pk-next { opacity: 0.6; }

modules/propresenter-timers/client.js

@@ -70,6 +70,7 @@ const DEFAULTS = {
   showDetail: true,
   showSeconds: true,
   leadingZeros: false,
+  showLoops: false,
   clock24h: true,
   clockSeconds: true,
   clockDate: false,
@@ -384,7 +385,12 @@ export default function create({ root, moduleApi }) {
       for (const source of state.sources) {
         for (const timer of source.timers) {
           if (keyOf(source, timer) !== solo) continue;
-          return [{ id: source.id, source, items: [{ key: solo, source, timer }] }];
+          // A solo video tile with looping media hidden must not sit empty:
+          // it shows a quiet card instead of a countdown nobody should read.
+          const shown = timer.looping && pref('showLoops') !== true
+            ? { ...timer, state: 'idle', remainingMs: null, elapsedMs: null, startedAt: null, asOf: null, status: { text: 'Looping', tone: 'muted' } }
+            : timer;
+          return [{ id: source.id, source, items: [{ key: solo, source, timer: shown }] }];
         }
       }
       // The timer this tile was added for is not offered right now. Nothing is
@@ -398,7 +404,11 @@ export default function create({ root, moduleApi }) {
       const items = [];
       for (const timer of source.timers) {
         const key = keyOf(source, timer);
-        if (!hidden.has(key)) items.push({ key, source, timer });
+        if (hidden.has(key)) continue;
+        // A looping background's time means nothing — the card sits out
+        // while a loop plays (per tile: the "Looping videos" switch).
+        if (timer.looping && pref('showLoops') !== true) continue;
+        items.push({ key, source, timer });
       }
       // Every timer of a live source hidden on purpose: nothing to say.
       if (!items.length && source.timers.length) continue;
@@ -666,7 +676,9 @@ export default function create({ root, moduleApi }) {
           card.mono = null;
         }
         text = value === null ? '—' : fmtDuration(value, { ...digits, up: timer.kind === 'countdown' });
-        tone = toneFor(timer, value);
+        // A shown loop never warns or overruns — it wraps at zero by design,
+        // and a background flashing red every pass would cry wolf all service.
+        tone = timer.looping ? (timer.state === 'running' ? 'ok' : 'muted') : toneFor(timer, value);
         statusText = timer.status?.text || defaultStatus(timer, value, tone);
         statusTone = timer.status?.tone || tone;
         detailText = timer.detail || '';

modules/propresenter-timers/ltc-listener.js

@@ -191,9 +191,13 @@ function createLtcListener({ device, channel, moduleDir, log, onUpdate }) {
     });
     if (!tool.ready) {
       report({ error: tool.error, detail: tool.detail });
-      // A build in flight restarts us itself when it lands; anything else is
+      // onReady is only the FAST path (a successful build restarts us at
-      // config-shaped and should back off hard rather than spin.
+      // once). The slow retry must stay armed regardless: a failed build
-      if (tool.error !== TOOL_BUILDING) scheduleRestart(BAD_CONFIG_RETRY_MS);
+      // never calls back, and a binary can also arrive from outside — scp'd
+      // in on a machine whose toolchain can't build (AB's broken CLT).
+      // Waiting on onReady alone deadlocked exactly that way in production:
+      // "Capture tool building…" forever, with a working binary on disk.
+      scheduleRestart(BAD_CONFIG_RETRY_MS);
       return;
     }
 

modules/propresenter-timers/module.json

@@ -1,7 +1,7 @@
 {
   "id": "propresenter-timers",
   "name": "Timers",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "proddash": ">=1.4.0",
   "description": "Timers, Clocks, and LTC From configured Modules",
   "provides": [
@@ -161,6 +161,12 @@
       "default": false,
       "group": "Show"
     },
+    "showLoops": {
+      "type": "switch",
+      "label": "Looping videos",
+      "default": false,
+      "group": "Show"
+    },
     "showHeadings": {
       "type": "switch",
       "label": "Source headings",

modules/propresenter-timers/server.js

@@ -255,6 +255,21 @@ function createProPresenterSource({ config, log }) {
   /** uuid → phase tracker: whole-second reports → one stable anchor (see phase.js). */
   const phases = new Map();
 
+  /* The video countdown — time left on what the presentation layer is
+     playing, from the transport routes (verified live on ProPresenter 21.4):
+       GET /v1/transport/presentation/current → { is_playing, uuid, name,
+         artist, audio_only, duration }   (no looping flag exists — inferred)
+       GET /v1/transport/presentation/time    → bare seconds, sub-second
+         float — better than /v1/timer/video_countdown's whole-second string,
+         so no quantization phase lock is needed, only an anchor hold. */
+  let media = null;      // { uuid, name, duration, playing } from the slow lane
+  let mediaAt = 0;
+  let transportOk = null; // null until the first answer; false = no transport route (older ProPresenter)
+  let videoPos = null;   // playback position in seconds (float)
+  let videoAsOf = 0;     // server ms when videoPos was measured
+  let videoAnchor = null; // published { remainingMs, asOf }, held while it predicts the measurements
+  let loopingUuid = '';  // media seen wrapping — a looping background
+
   function url(target) {
     const built = new URL(`http://${host}:${port}${target}`);
     if (password) built.searchParams.set('password', password);
@@ -390,6 +405,121 @@ function createProPresenterSource({ config, log }) {
     return out;
   }
 
+  /**
+   * Follow the presentation transport layer. Failures here only drop the
+   * video card, never the whole source — the timers must survive a
+   * ProPresenter build with transport quirks.
+   */
+  async function pollVideo() {
+    if (tick % SLOW_EVERY === 1) {
+      try {
+        const raw = await requestJson('/v1/transport/presentation/current');
+        const uuid = String(raw?.uuid || '');
+        if (!media || media.uuid !== uuid) {
+          if (media && media.uuid !== uuid) loopingUuid = '';
+          videoPos = null;
+          videoAnchor = null;
+        }
+        media = uuid ? {
+          uuid,
+          name: String(raw.name || ''),
+          duration: Number(raw.duration) > 0 ? Number(raw.duration) : 0,
+          playing: Boolean(raw.is_playing),
+        } : null;
+        mediaAt = Date.now();
+        transportOk = true;
+      } catch (err) {
+        media = null; // the slow lane retries in ~2 s
+        if (err && err.status === 404) transportOk = false; // no transport route on this build
+      }
+    }
+    if (!media) {
+      videoPos = null;
+      videoAnchor = null;
+      return;
+    }
+    try {
+      const pos = Number(await requestJson('/v1/transport/presentation/time'));
+      if (Number.isFinite(pos) && pos >= 0) {
+        // Same media, position jumped back by more than a stutter: it
+        // wrapped — a looping background. Sticks until the media changes.
+        // (A video manually re-triggered from the start looks the same and
+        // is mislabeled for that pass; loops re-wrap, replays don't recur.)
+        if (videoPos !== null && media.playing && videoPos - pos > 1.5) loopingUuid = media.uuid;
+        videoPos = pos;
+        videoAsOf = Date.now();
+      } else {
+        videoPos = null;
+      }
+    } catch {
+      videoPos = null;
+    }
+  }
+
+  /** The video countdown as one synthetic timer card (id 'video'). The card
+      persists as an idle "—" between videos — a wall tile must not appear
+      and vanish with the media — and is only absent entirely on a
+      ProPresenter without transport routes. */
+  function videoTimer() {
+    if (transportOk !== true) return null;
+    if (!media) {
+      return {
+        id: 'video',
+        label: 'Video',
+        kind: 'countdown',
+        state: 'idle',
+        asOf: mediaAt || updatedAt,
+        startedAt: null,
+        elapsedMs: null,
+        remainingMs: null,
+        targetMs: null,
+        looping: false,
+        status: null,
+        detail: '',
+      };
+    }
+    const playing = media.playing;
+    const dur = media.duration > 0 ? media.duration * 1000 : null;
+    let remainingMs = null;
+    let asOf = videoAsOf || mediaAt;
+    if (videoPos !== null && dur !== null) {
+      remainingMs = Math.max(0, dur - videoPos * 1000);
+      if (playing) {
+        // Hold the published anchor while it still predicts the measured
+        // position: the tiles extrapolate locally, and a fresh anchor per
+        // poll would broadcast a frame every 500 ms for nothing.
+        const p = videoAnchor;
+        const predicted = p ? p.remainingMs - (videoAsOf - p.asOf) : NaN;
+        if (p && Math.abs(predicted - remainingMs) < 120) {
+          remainingMs = p.remainingMs;
+          asOf = p.asOf;
+        } else {
+          videoAnchor = { remainingMs, asOf };
+        }
+      } else {
+        videoAnchor = null;
+      }
+    } else {
+      videoAnchor = null;
+    }
+    const looping = media.uuid === loopingUuid;
+    return {
+      id: 'video',
+      label: 'Video',
+      kind: 'countdown',
+      state: playing ? 'running' : videoPos > 0 ? 'paused' : 'idle',
+      asOf,
+      startedAt: null,
+      elapsedMs: remainingMs !== null && dur !== null ? dur - remainingMs : null,
+      remainingMs,
+      targetMs: dur,
+      looping,
+      status: looping ? { text: playing ? 'Looping' : 'Paused', tone: 'muted' } : null,
+      // The media name, without the file extension nobody reads on a wall.
+      detail: media.name.replace(/\.(mp4|mov|m4v|mxf|avi|mkv|mp3|wav|aiff?)$/i, ''),
+    };
+  }
+
   function status() {
     if (!configured) return 'error';
     if (reachable) return 'ok';
@@ -429,6 +559,9 @@ function createProPresenterSource({ config, log }) {
       const currentTimes = await requestJson('/v1/timers/current');
       updatedAt = Date.now();
       timers = mergeTimers(currentTimes, updatedAt);
+      await pollVideo();
+      const video = videoTimer();
+      if (video) timers.push(video);
       reachable = true;
       lastError = '';
     } catch (err) {
@@ -970,6 +1103,8 @@ const GEAR = {
   all: { instanceSchema: FULL_SCHEMA, instanceGroups: FULL_GROUPS },
   /** One ProPresenter or module timer: its elements, and the tone its digits take per state. */
   timer: gearOf([...TIMER_ELEMENTS, ...COLOURS], OPEN_COLOURS),
+  /** The video countdown: a timer card, plus whether looping media counts. */
+  video: gearOf([...TIMER_ELEMENTS, 'showLoops', ...COLOURS], OPEN_COLOURS),
   /** The timecode: running, no signal (warning) and stopped (idle) — it never overruns, and frames are frames. */
   ltc: gearOf(['showNames', 'showStatus', 'runningColor', 'warningColor', 'idleColor'], OPEN_COLOURS),
   /** The time of day: plain digits, so only how they read. */
@@ -983,6 +1118,7 @@ function gearFor(source, timer) {
   if (source.kind === 'ltc') return GEAR.ltc;
   if (source.kind === 'clock') return GEAR.clock;
   if (timer.kind === 'clock') return GEAR.providerClock;
+  if (source.id === 'propresenter' && timer.id === 'video') return GEAR.video;
   return GEAR.timer;
 }
 
@@ -1191,6 +1327,7 @@ module.exports = {
       for (const t of src.timers) {
         const description = src.kind === 'ltc' ? 'The incoming LTC timecode on its own'
           : src.kind === 'clock' ? 'The time of day on its own'
+            : src.id === 'propresenter' && t.id === 'video' ? 'Time left on the video ProPresenter is playing'
               : `This ${src.label} ${KIND_WORD[t.kind] || 'timer'} on its own`;
         // Layouts from before 1.3.0 hold 'timer:<uuid>' / 'ltc' — the same tiles.
         const aliases = src.id === 'propresenter' ? [`timer:${t.id}`] : src.kind === 'ltc' ? ['ltc'] : [];

modules/spl-meter/module.json

@@ -1,7 +1,7 @@
 {
   "id": "spl-meter",
   "name": "SPL Meter",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "proddash": ">=1.5.0",
   "description": "Calibrated sound level, Leq and RTA from an audio input on this machine",
   "permissions": [

modules/spl-meter/server.js

@@ -20,7 +20,7 @@
  */
 
 const path = require('path');
-const { createSplListener } = require('./spl-listener');
+const { createSplListener, ensureCaptureBinary } = require('./spl-listener');
 
 /** Reference level of a sound level calibrator. Effectively always 94 dB. */
 const CALIBRATOR_DB = 94;
@@ -114,11 +114,19 @@ module.exports = {
       error: '',
       streams: new Set(),
       silentSince: null,
+      toolMissing: '',
       listener: null,
       lastSent: '',
       pinger: null,
     };
 
+    // Before anything else: the device picker shells out to this tool, so a
+    // machine that installed the module from the catalog (source only — the
+    // binary is gitignored) needs the build kicked off here. Waiting for a
+    // listener would never happen: no tool means no device list, and no
+    // device means no listener.
+    state.toolMissing = ensureCaptureBinary({ moduleDir, log });
+
     if (!config.enabled) {
       state.error = 'Sound level measurement is off — turn it on in ProdDash settings';
       return { stop() { teardown(); }, health: () => ({ status: 'error', message: state.error }) };
@@ -177,6 +185,9 @@ module.exports = {
     return {
       stop() { teardown(); },
       health() {
+        if (state.toolMissing && !fsExists(path.join(moduleDir, 'spl-capture'))) {
+          return { status: 'error', message: state.toolMissing };
+        }
         if (state.error) return { status: 'error', message: state.error };
         if (!state.frame) return { status: 'connecting', message: 'waiting for the first reading' };
         const quiet = silentMs();
@@ -300,6 +311,13 @@ module.exports = {
       /** Device list for the admin page. Runs the capture tool's --list,
           which is the only thing that knows what CoreAudio can see. */
       'GET /devices': async (req, res) => {
+        const missing = ensureCaptureBinary({ moduleDir: __dirname, log });
+        if (missing) {
+          if (state) state.toolMissing = missing;
+          log(`device list unavailable — ${missing}`);
+          json(res, 200, { options: [] });
+          return;
+        }
         try {
           const devices = await listDevices();
           json(res, 200, {
@@ -438,6 +456,10 @@ function listDevices() {
   });
 }
 
+function fsExists(p) {
+  try { return require('fs').existsSync(p); } catch { return false; }
+}
+
 function json(res, code, body) {
   const text = JSON.stringify(body);
   res.writeHead(code, {

modules/spl-meter/spl-listener.js

@@ -17,7 +17,8 @@
  * module's ltc-capture. It normally arrives already built — compiled beside
  * the app, or copied from any Mac of the same architecture. When it is
  * missing this will build it, but in the background and never on the event
- * loop: see ensureBinary for what that cost the first time it was wrong.
+ * loop, and from module scope so the device picker can trigger it too — see
+ * ensureCaptureBinary for what both of those cost the first time round.
  *
  * The same macOS gotcha applies as for LTC, and is worth repeating because
  * it costs an afternoon every time: a ProdDash launched over SSH or from a
@@ -30,6 +31,74 @@ const path = require('path');
 const fs = require('fs');
 const { spawn } = require('child_process');
 
+const BUILD_HELP = 'Sound level capture tool missing — build it on any Apple Silicon Mac with '
+  + '`swiftc -O -o modules/spl-meter/spl-capture modules/spl-meter/spl-capture.swift` '
+  + 'and copy it next to spl-capture.swift';
+const BUILDING = 'Building the capture tool — this takes a minute or two';
+
+/**
+ * Build the capture tool if it is missing, WITHOUT blocking, and shared by
+ * everything that needs it.
+ *
+ * This lives at module scope rather than inside a listener because of a trap
+ * the first version walked into: the admin page's device picker runs the tool
+ * with --list, but the build only ran when a listener started, and a listener
+ * only starts once a device has been picked. On a machine that got the module
+ * from the catalog — source only, the binary being gitignored — the picker
+ * was empty, and nothing would ever fill it.
+ *
+ * It also must never block. It was a spawnSync once, copied from the LTC
+ * listener where the source is a third the size and builds in seconds. Here
+ * it took nearly two minutes on the production Mac and held the Node event
+ * loop for all of it, freezing every other module, then did it again on the
+ * next retry.
+ *
+ * The binary should normally already be there: built beside the app, or
+ * copied from any Mac of the same architecture. This is the fallback.
+ *
+ * @returns {string} '' when the tool is ready, otherwise what to say.
+ */
+let building = false;
+let buildFailed = false;
+
+function ensureCaptureBinary({ moduleDir, log, onReady }) {
+  const bin = path.join(moduleDir, 'spl-capture');
+  if (fs.existsSync(bin)) return '';
+  const src = bin + '.swift';
+  if (!fs.existsSync(src)) return 'spl-capture.swift is missing from the module folder';
+  if (building) return BUILDING;
+  if (buildFailed) return BUILD_HELP;
+
+  building = true;
+  log('spl-capture binary missing — building it in the background');
+  const build = spawn('swiftc', ['-O', '-o', bin, src], { stdio: ['ignore', 'ignore', 'pipe'] });
+  let buildErr = '';
+  build.stderr.setEncoding('utf8');
+  build.stderr.on('data', (t) => { buildErr = (buildErr + t).slice(-800); });
+  const giveUp = setTimeout(() => {
+    try { build.kill('SIGKILL'); } catch { /* already gone */ }
+  }, 300000);
+  build.on('error', (err) => {
+    clearTimeout(giveUp);
+    building = false; buildFailed = true;
+    log(`swiftc could not be run: ${err.message}`);
+  });
+  build.on('exit', (code) => {
+    clearTimeout(giveUp);
+    building = false;
+    if (code === 0 && fs.existsSync(bin)) {
+      log('spl-capture built');
+      buildFailed = false;
+      if (typeof onReady === 'function') onReady();
+      return;
+    }
+    buildFailed = true;
+    log(`spl-capture build failed (exit ${code})`
+      + (buildErr ? `: ${buildErr.trim().split('\n').pop()}` : ''));
+  });
+  return BUILDING;
+}
+
 const RESTART_MS = 5000;
 /** An immediate exit is config-shaped (bad device, channel out of range) —
     retrying every 5 s would only fill the log with the same sentence. */
@@ -53,64 +122,13 @@ function createSplListener(opts) {
   let stallTimer = null;
   let startedAt = 0;
   let meta = null;
-  let building = false;
-  let buildFailed = false;
   let lastFrameWall = 0;
 
-  const BUILD_HELP = 'Sound level capture tool missing — build it on any Apple Silicon Mac with '
+  /** '' when the tool is ready, otherwise what to say about it. */
-    + '`swiftc -O -o modules/spl-meter/spl-capture modules/spl-meter/spl-capture.swift` '
-    + 'and copy it next to spl-capture.swift';
-
-  /**
-   * Build the capture tool if it is missing, WITHOUT blocking.
-   *
-   * This used to be a spawnSync, copied from the LTC listener where the
-   * source is a third the size and builds in a few seconds. Here it took
-   * nearly two minutes on the production Mac and froze the entire ProdDash
-   * server for every second of it — one module's optional helper took the
-   * whole dashboard down, then did it again on every retry. Nothing that
-   * runs while a service might be on is allowed to hold the event loop.
-   *
-   * The build is a fallback for a module installed from the catalog on a
-   * machine with a Swift toolchain. The normal path is a binary built
-   * alongside the app, or copied from any same-architecture Mac.
-   *
-   * @returns {string} '' when the binary is ready, otherwise what to say.
-   */
   function ensureBinary() {
-    if (fs.existsSync(bin)) return '';
+    return ensureCaptureBinary({ moduleDir, log, onReady() {
-    const src = bin + '.swift';
-    if (!fs.existsSync(src)) return 'spl-capture.swift is missing from the module folder';
-    if (building) return 'Building the capture tool — this takes a minute or two';
-    if (buildFailed) return BUILD_HELP;
-
-    building = true;
-    log('spl-capture binary missing — building it in the background');
-    const build = spawn('swiftc', ['-O', '-o', bin, src], { stdio: ['ignore', 'ignore', 'pipe'] });
-    let buildErr = '';
-    build.stderr.setEncoding('utf8');
-    build.stderr.on('data', (t) => { buildErr = (buildErr + t).slice(-800); });
-    const giveUp = setTimeout(() => {
-      try { build.kill('SIGKILL'); } catch { /* already gone */ }
-    }, 300000);
-    build.on('error', (err) => {
-      clearTimeout(giveUp);
-      building = false; buildFailed = true;
-      log(`swiftc could not be run: ${err.message}`);
-    });
-    build.on('exit', (code) => {
-      clearTimeout(giveUp);
-      building = false;
-      if (code === 0 && fs.existsSync(bin)) {
-        log('spl-capture built');
-        buildFailed = false;
       if (!stopped) { clearTimeout(restartTimer); restartTimer = null; start(); }
-        return;
+    } });
-      }
-      buildFailed = true;
-      log(`spl-capture build failed (exit ${code})` + (buildErr ? `: ${buildErr.trim().split('\n').pop()}` : ''));
-    });
-    return 'Building the capture tool — this takes a minute or two';
   }
 
   function scheduleRestart(ms) {
@@ -135,9 +153,13 @@ function createSplListener(opts) {
     const missing = ensureBinary();
     if (missing) {
       onUpdate({ error: missing });
-      // A build in flight calls start() itself when it lands; anything else
+      // onReady is only the FAST path (a successful build restarts us at
-      // is config-shaped and should back off hard rather than spin.
+      // once). The slow retry must stay armed regardless: a failed build
-      if (!building) scheduleRestart(BAD_CONFIG_RETRY_MS);
+      // never calls back, and a binary can also arrive from outside — scp'd
+      // in on a machine whose toolchain can't build (AB's broken CLT).
+      // Waiting on onReady alone deadlocked exactly that way in the Timers
+      // module: "building…" forever, with a working binary on disk.
+      scheduleRestart(BAD_CONFIG_RETRY_MS);
       return;
     }
 
@@ -236,4 +258,4 @@ function createSplListener(opts) {
   };
 }
 
-module.exports = { createSplListener };
+module.exports = { createSplListener, ensureCaptureBinary };

package.json

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

public/admin/admin.css

@@ -443,6 +443,7 @@ a.btn { text-decoration: none; }
   margin-bottom: 10px;
 }
 .catalog-main { flex: 1; min-width: 0; }
+.catalog-pick { margin: 5px 10px 0 0; flex: none; }
 .catalog-title { display: flex; align-items: center; gap: 8px; }
 .catalog-row .module-desc { margin: 4px 0 2px; }
 .catalog-row .module-health { margin-top: 2px; }

public/admin/admin.js

@@ -962,6 +962,13 @@ async function loadState() {
   for (const mod of state.modules || []) {
     modulesList.appendChild(buildModuleCard(mod));
   }
+  if (!(state.modules || []).length) {
+    // A packaged ProdDash starts like this: the catalog below is the way in.
+    const none = document.createElement('div');
+    none.className = 'layouts-empty';
+    none.textContent = 'Nothing installed yet — pick from Available modules below.';
+    modulesList.appendChild(none);
+  }
   renderPin(state);
   loadTheme();
   loadLayouts();
@@ -1163,6 +1170,7 @@ function renderAvailable(cat) {
     els.updateSlot.appendChild(btn);
   }
   const available = cat.available || [];
+  installSelectedBtn.hidden = available.filter((a) => a.compatible).length < 2;
   if (!available.length) {
     const none = document.createElement('div');
     none.className = 'layouts-empty';
@@ -1205,11 +1213,46 @@ function renderAvailable(cat) {
     btn.disabled = !item.compatible;
     btn.title = item.compatible ? '' : item.reason;
     btn.addEventListener('click', () => installFromCatalog(item, btn));
+    if (item.compatible) {
+      const pick = document.createElement('input');
+      pick.type = 'checkbox';
+      pick.className = 'catalog-pick';
+      pick.dataset.id = item.id;
+      pick.dataset.name = item.name;
+      pick.title = 'Tick several, then Install selected';
+      row.append(pick);
+    }
     row.append(main, btn);
     availableList.appendChild(row);
   }
 }
 
+const installSelectedBtn = document.getElementById('install-selected');
+
+/** The ticked modules, in one request; the answer says which ones landed. */
+async function installSelected() {
+  const picks = [...availableList.querySelectorAll('.catalog-pick:checked')];
+  if (!picks.length) return toast('Tick the modules to install first', true);
+  installSelectedBtn.disabled = true;
+  installSelectedBtn.textContent = `Installing ${picks.length}…`;
+  try {
+    const r = await api('/api/admin/modules/install', { method: 'POST', body: JSON.stringify({ ids: picks.map((p) => p.dataset.id) }) });
+    const done = (r.results || []).filter((x) => x.ok).length;
+    const failed = (r.results || []).filter((x) => !x.ok);
+    toast(failed.length
+      ? `${done} installed; ${failed.map((f) => `${f.id}: ${f.error}`).join(' · ')}`
+      : `${done} module${done === 1 ? '' : 's'} installed`, failed.length > 0);
+    await loadState();
+  } catch (e) {
+    if (e.authRequired) showLogin();
+    else toast(e.message, true);
+  } finally {
+    installSelectedBtn.disabled = false;
+    installSelectedBtn.textContent = 'Install selected';
+  }
+}
+installSelectedBtn.addEventListener('click', installSelected);
+
 async function installFromCatalog(item, btn) {
   btn.disabled = true;
   const label = btn.textContent;

public/admin/index.html

@@ -58,6 +58,7 @@
     <section id="available-section" hidden>
       <h1 class="admin-h1">Available modules</h1>
       <div class="catalog-toolbar">
+        <button class="btn small primary" id="install-selected" hidden>Install selected</button>
         <button class="btn small" id="catalog-refresh">Check again</button>
         <span class="admin-status" id="catalog-status"></span>
       </div>

public/shell.js

@@ -510,6 +510,7 @@ function reconcileOfferedTiles() {
   }
   if (changed) rebuildDividers();
   scheduleOfferedRecheck();
+  refreshEmptyState(); // the registry may have gone from nothing to something
 }
 
 /* A module's entry list can change without anyone saving admin config: PCO
@@ -676,6 +677,15 @@ function buildTile(tile) {
 
 function refreshEmptyState() {
   emptyEl.hidden = tiles.length > 0;
+  if (emptyEl.hidden) return;
+  // Two different empties: a bare board, and a ProdDash with nothing to put
+  // on one — a packaged install starts without modules until Admin adds some.
+  const noModules = registry.size === 0;
+  if (noModules === emptyEl.classList.contains('no-modules')) return;
+  emptyEl.classList.toggle('no-modules', noModules);
+  emptyEl.innerHTML = noModules
+    ? 'No modules yet — <a href="/admin">open Admin</a> and install some under Available modules.'
+    : 'No tiles yet — use “＋ Add tile” to build this dashboard.<br>Every browser keeps its own layout.';
 }
 
 /* ── drag to move ───────────────────────────────────────────────────── */

server.js

@@ -277,6 +277,52 @@ function isUninstalled(id) {
   return moduleState(id).uninstalled === true;
 }
 
+/**
+ * A packaged install that still carries modules in its app folder — every
+ * install made before 1.10.0 does — moves them into the data directory
+ * once, as installed copies, and drops the app-folder copies. Nothing
+ * changes for the operator: the same modules run with the same settings
+ * (config is keyed by module id), and from now on each updates on its own
+ * from the catalog. A compiled helper sitting in a bundled folder travels
+ * with it. A module the operator had uninstalled is simply dropped — the
+ * catalog still offers it, and its settings stay in modules.json.
+ */
+function unbundleModules() {
+  if (!PACKAGED || !fs.existsSync(BUNDLED_MODULES_DIR)) return;
+  const installed = new Map(readManifests(INSTALLED_MODULES_DIR, 'installed').map((m) => [m.id, m]));
+  let moved = 0;
+  let failed = 0;
+  for (const man of readManifests(BUNDLED_MODULES_DIR, 'bundled')) {
+    if (isUninstalled(man.id)) continue;
+    const copy = installed.get(man.id);
+    if (copy && compareVersions(copy.version, man.version) >= 0) continue; // the data directory already has as good or better
+    const dest = path.join(INSTALLED_MODULES_DIR, man.id);
+    const staging = path.join(INSTALLED_MODULES_DIR, `.${man.id}.moving`);
+    try {
+      fs.mkdirSync(INSTALLED_MODULES_DIR, { recursive: true });
+      fs.rmSync(staging, { recursive: true, force: true });
+      fs.cpSync(man.dir, staging, { recursive: true }); // keeps modes: a compiled helper stays executable
+      fs.rmSync(dest, { recursive: true, force: true });
+      fs.renameSync(staging, dest);
+      moved += 1;
+      console.log(`[proddash] moved bundled module "${man.id}" v${man.version} into the data directory${copy ? ` (over the installed v${copy.version})` : ''}`);
+    } catch (err) {
+      failed += 1;
+      console.error(`[proddash] could not move bundled module "${man.id}" into the data directory:`, err?.message || err);
+    }
+  }
+  if (failed) {
+    console.warn(`[proddash] ${failed} bundled module${failed === 1 ? '' : 's'} stay in the app folder for now — tried again at the next start`);
+    return;
+  }
+  try {
+    fs.rmSync(BUNDLED_MODULES_DIR, { recursive: true, force: true });
+    console.log(`[proddash] the app folder carries no modules now${moved ? ` — ${moved} moved into the data directory` : ''}; the admin page's catalog installs and updates them`);
+  } catch (err) {
+    console.warn("[proddash] could not remove the app folder's modules:", err?.message || err);
+  }
+}
+
 function moduleState(id) {
   const s = modulesConfig[id];
   return s && typeof s === 'object' ? s : {};
@@ -373,7 +419,18 @@ function mountModule(id) {
   const log = makeLog(id);
   try {
     const serverPath = path.join(man.dir, man.server);
-    // Re-require fresh config on every (re)mount; the module code itself stays cached.
+    // Drop the module's code from the require cache so every (re)mount runs
+    // the files on disk. Without this a module UPDATE swaps the folder while
+    // the process keeps executing the old code until ProdDash itself
+    // restarts — the manifest (read fresh from disk) then reports a version
+    // the running code isn't, and anything new in the update silently
+    // doesn't happen. Modules already have to come up clean on re-init
+    // (module guide), so a fresh load on config remounts is the same
+    // contract without the trap.
+    const cachePrefix = man.dir.endsWith(path.sep) ? man.dir : man.dir + path.sep;
+    for (const key of Object.keys(require.cache)) {
+      if (key.startsWith(cachePrefix)) delete require.cache[key];
+    }
     const mod = require(serverPath);
     const config = effectiveConfig(id);
     // What a module needs to reach the rest of ProdDash — another module's
@@ -1060,13 +1117,22 @@ async function installModule(id) {
   if (download) {
     const staging = path.join(INSTALLED_MODULES_DIR, `.${id}.installing`);
     fs.rmSync(staging, { recursive: true, force: true });
+    const shipped = new Set();
     for (const [rel, data] of remoteEntry.files) {
       if (!safeRelPath(rel)) continue;
+      shipped.add(rel);
       const target = path.join(staging, rel);
       fs.mkdirSync(path.dirname(target), { recursive: true });
       fs.writeFileSync(target, data);
     }
     const dest = path.join(INSTALLED_MODULES_DIR, id);
+    // Per-machine executables — a capture tool compiled here, or copied in
+    // by hand on a machine whose toolchain can't build it — are gitignored,
+    // so the repo never ships them. Replacing the folder must not destroy
+    // them: carry executables the download doesn't include over from the
+    // copy being replaced (or from the app's bundled copy on a first
+    // install), or "update" quietly kills a working module.
+    carryOverExecutables([dest, path.join(BUNDLED_MODULES_DIR, id)], staging, shipped);
     unmountModule(id);
     fs.rmSync(dest, { recursive: true, force: true });
     fs.renameSync(staging, dest);
@@ -1083,6 +1149,43 @@ async function installModule(id) {
   return { id, version: String(now?.version || ''), source: now?.source || '', downloaded: download };
 }
 
+/**
+ * Copy executable files (any execute bit) that `shipped` does not include
+ * from the first existing source dir into `staging`, keeping their relative
+ * path and mode. Executables only, on purpose: they are the per-machine
+ * build artifacts (gitignored, so never in a download), while stray text
+ * files from an old version — code an update deliberately removed — must
+ * NOT be resurrected.
+ */
+function carryOverExecutables(sourceDirs, staging, shipped) {
+  const from = sourceDirs.find((d) => {
+    try { return fs.statSync(d).isDirectory(); } catch { return false; }
+  });
+  if (!from) return;
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(from, rel), { withFileTypes: true })) {
+      const relPath = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        walk(relPath);
+        continue;
+      }
+      if (!e.isFile() || shipped.has(relPath) || !safeRelPath(relPath)) continue;
+      try {
+        const stat = fs.statSync(path.join(from, relPath));
+        if (!(stat.mode & 0o111)) continue;
+        const target = path.join(staging, relPath);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.copyFileSync(path.join(from, relPath), target);
+        fs.chmodSync(target, stat.mode);
+        console.log(`[proddash] module update kept per-machine executable "${relPath}"`);
+      } catch (err) {
+        console.error(`[proddash] could not carry "${relPath}" across the update:`, err?.message || err);
+      }
+    }
+  };
+  walk('');
+}
+
 /** Remove a module: an installed copy is deleted; a bundled one is switched
     off and hidden (its folder belongs to the app). Settings are kept so a
     later reinstall picks them up again. */
@@ -1178,9 +1281,18 @@ const DATA_DIR_INSIDE_ROOT = (() => {
   return rel.split(path.sep).join('/') + '/';
 })();
 
+/* A packaged install — the macOS app, the Windows bundle: anything that is
+   not a git checkout, the same test the updater uses to choose the archive
+   over git pull — carries no modules of its own. Every module comes from
+   the catalog into the data directory, and the shell's own update never
+   brings one along. A checkout keeps running the modules in its tree, which
+   is what development wants. */
+const PACKAGED = !fs.existsSync(path.join(ROOT, '.git'));
+
 function isKeptOnUpdate(rel) {
   if (rel.startsWith('.git/')) return true;
   if (rel === 'config/modules.json' || rel.startsWith('config/layouts/')) return true;
+  if (PACKAGED && (rel === 'modules' || rel.startsWith('modules/'))) return true;
   return Boolean(DATA_DIR_INSIDE_ROOT) && `${rel}/`.startsWith(DATA_DIR_INSIDE_ROOT);
 }
 
@@ -1523,6 +1635,29 @@ async function handleAdminApi(req, res, urlPath) {
     return;
   }
 
+  // Several at once — a fresh install picking its set. One result per id;
+  // a failure stops nothing else.
+  if (urlPath === '/api/admin/modules/install' && req.method === 'POST') {
+    if (refuseAdminWrite(req, res)) return;
+    let body = {};
+    try {
+      body = JSON.parse((await readBody(req)) || '{}');
+    } catch {
+      return sendJson(res, 400, { error: 'Malformed request.' });
+    }
+    const ids = Array.isArray(body.ids) ? [...new Set(body.ids.map((id) => String(id)))] : [];
+    if (!ids.length) return sendJson(res, 400, { error: 'Nothing to install.' });
+    const results = [];
+    for (const id of ids) {
+      try {
+        results.push({ ok: true, ...(await installModule(id)) });
+      } catch (err) {
+        results.push({ ok: false, id, error: err?.message || String(err) });
+      }
+    }
+    return sendJson(res, 200, { ok: results.every((r) => r.ok), results });
+  }
+
   const install = urlPath.match(/^\/api\/admin\/modules\/([^/]+)\/install$/);
   if (install && req.method === 'POST') {
     if (refuseAdminWrite(req, res)) return;
@@ -2017,6 +2152,7 @@ server.requestTimeout = 0;
 
 /* ── boot ───────────────────────────────────────────────────────────── */
 
+unbundleModules();
 discoverModules();
 mountAllModules();
 

tools/pp-timers-mock.js

@@ -152,10 +152,39 @@ const server = http.createServer((req, res) => {
   if (p === '/v1/timers') return sendJson(res, TIMERS.filter((t) => !DROP.has(t.id.uuid)));
   if (p === '/v1/timers/current') return sendJson(res, currentTimes().filter((t) => !DROP.has(t.id.uuid)));
   if (p === '/v1/timecode/status' && !NO_LTC) return sendJson(res, timecodeStatus());
+  if (p === '/v1/transport/presentation/current') return sendJson(res, transport().current);
+  if (p === '/v1/transport/presentation/time') return sendJson(res, transport().time);
 
   sendJson(res, { error: 'not found' }, 404);
 });
 
+/* ── transport (video countdown): a 4-minute cycle ─────────────────
+   0–60 s   "Sermon Bumper.mp4" (3:00) playing
+   60–75 s  the same bumper paused at 1:00
+   75–90 s  playing again
+   90–120 s nothing loaded
+   120–240 s "Autumn Loop.mp4" (0:15) playing and wrapping — the module
+             must infer looping from the position jumping back.
+   Shapes match ProPresenter 21.4 live: `current` = { is_playing, uuid,
+   name, artist, audio_only, duration }, `time` = bare seconds (float). */
+function transport() {
+  const phase = ((Date.now() - startedAt) / 1000) % 240;
+  const none = { current: { is_playing: false, uuid: '', name: '', artist: '', audio_only: false, duration: 0 }, time: -1 };
+  if (phase < 90) {
+    const playing = phase < 60 || phase >= 75;
+    const pos = Math.min(phase, 60) + (phase >= 75 ? phase - 75 : 0);
+    return {
+      current: { is_playing: playing, uuid: 'MEDIA-BUMPER', name: 'Sermon Bumper.mp4', artist: '', audio_only: false, duration: 180 },
+      time: Math.round(pos * 10) / 10,
+    };
+  }
+  if (phase < 120) return none;
+  return {
+    current: { is_playing: true, uuid: 'MEDIA-LOOP', name: 'Autumn Loop.mp4', artist: '', audio_only: false, duration: 15 },
+    time: Math.round(((phase - 120) % 15) * 10) / 10,
+  };
+}
+
 /* ── stage-display websocket (/stagedisplay) ─────────────────────── */
 
 const cryptoMod = require('crypto');

tools/unbundled.test.js

@@ -0,0 +1,203 @@
+'use strict';
+
+/**
+ * A packaged ProdDash carries no modules. This drives a packaged copy of the
+ * shell — server.js and its client in a folder with no .git — through the
+ * three things that make that true:
+ *
+ *   1. an install made before 1.10.0 still has modules in its app folder:
+ *      at boot they move into the data directory once, executables keeping
+ *      their mode, an uninstalled one is dropped, and the app folder's
+ *      modules/ is gone;
+ *   2. a shell update from an archive that carries modules/ never writes
+ *      them into the app folder — they show up in the catalog instead;
+ *   3. a fresh install lists everything the repo offers, and installing
+ *      several at once lands them in the data directory and mounts them.
+ *
+ *   node tools/unbundled.test.js
+ *
+ * Plain Node, no dependencies: a mock forge, a temp app folder, a temp data
+ * directory. Exits non-zero on the first failure and cleans up after itself.
+ */
+
+const assert = require('node:assert/strict');
+const { spawn, execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const http = require('node:http');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO = path.join(__dirname, '..');
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const probe = net.createServer();
+    probe.listen(0, '127.0.0.1', () => {
+      const { port } = probe.address();
+      probe.close(() => resolve(port));
+    });
+    probe.on('error', reject);
+  });
+}
+
+async function waitFor(url, ms = 15000) {
+  const deadline = Date.now() + ms;
+  let last = '';
+  while (Date.now() < deadline) {
+    try {
+      const r = await fetch(url);
+      if (r.ok) return;
+      last = 'HTTP ' + r.status;
+    } catch (err) {
+      last = err.message;
+    }
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  throw new Error('server did not come up: ' + last);
+}
+
+function writeModule(dir, id, version, extra = {}) {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'module.json'), JSON.stringify({ id, name: id[0].toUpperCase() + id.slice(1), version, client: 'client.js', ...extra }));
+  fs.writeFileSync(path.join(dir, 'client.js'), 'export default function () {}\n');
+}
+
+/** The repo as a forge would archive it: one top-level folder, the shell files, and modules/. */
+function buildArchive(dir) {
+  const top = path.join(dir, 'ProdDash-main');
+  fs.mkdirSync(top, { recursive: true });
+  fs.copyFileSync(path.join(REPO, 'server.js'), path.join(top, 'server.js'));
+  fs.writeFileSync(path.join(top, 'package.json'), JSON.stringify({ name: 'proddash', version: '9.9.9' }));
+  writeModule(path.join(top, 'modules', 'demo'), 'demo', '2.0.0');
+  writeModule(path.join(top, 'modules', 'other'), 'other', '1.0.0');
+  writeModule(path.join(top, 'modules', 'third'), 'third', '1.0.0');
+  const out = path.join(dir, 'main.tar.gz');
+  execFileSync('tar', ['-czf', out, '-C', dir, 'ProdDash-main']);
+  return fs.readFileSync(out);
+}
+
+/** A packaged install as it was before 1.10.0: the shell plus bundled modules, no .git. */
+function buildPackagedApp(app) {
+  fs.mkdirSync(path.join(app, 'config'), { recursive: true });
+  fs.copyFileSync(path.join(REPO, 'server.js'), path.join(app, 'server.js'));
+  fs.copyFileSync(path.join(REPO, 'package.json'), path.join(app, 'package.json'));
+  fs.cpSync(path.join(REPO, 'public'), path.join(app, 'public'), { recursive: true });
+  fs.writeFileSync(path.join(app, 'config', 'proddash.json'), JSON.stringify({ port: 24500 }));
+  writeModule(path.join(app, 'modules', 'demo'), 'demo', '1.0.0');
+  fs.mkdirSync(path.join(app, 'modules', 'demo', 'bin'));
+  fs.writeFileSync(path.join(app, 'modules', 'demo', 'bin', 'demo-helper'), '#!/bin/sh\necho helper\n');
+  fs.chmodSync(path.join(app, 'modules', 'demo', 'bin', 'demo-helper'), 0o755);
+  writeModule(path.join(app, 'modules', 'gone'), 'gone', '1.0.0');
+}
+
+(async () => {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'proddash-unbundled-'));
+  const app = path.join(work, 'app');
+  const dataDir = path.join(work, 'data');
+  fs.mkdirSync(dataDir);
+  buildPackagedApp(app);
+  // The operator had uninstalled "gone" before this update.
+  fs.writeFileSync(path.join(dataDir, 'modules.json'), JSON.stringify({ gone: { uninstalled: true } }));
+  const archive = buildArchive(path.join(work, 'forge'));
+
+  const forge = http.createServer((req, res) => {
+    if (req.url.startsWith('/michael/ProdDash/archive/main.tar.gz')) {
+      res.writeHead(200, { 'Content-Type': 'application/gzip' });
+      return res.end(archive);
+    }
+    res.writeHead(404);
+    res.end();
+  });
+  const forgePort = await freePort();
+  await new Promise((r) => forge.listen(forgePort, '127.0.0.1', r));
+
+  const port = await freePort();
+  const base = `http://127.0.0.1:${port}`;
+  const env = {
+    ...process.env,
+    PRODDASH_DATA_DIR: dataDir,
+    PORT: String(port),
+    PRODDASH_FORGE: `http://127.0.0.1:${forgePort}`,
+    PRODDASH_REPO: 'michael/ProdDash',
+    PRODDASH_NO_REMOTE_CHECK: '1',
+    PRODDASH_LAUNCHER: '1', // a supervisor is watching: an update exits 75 instead of respawning
+  };
+  let log = '';
+  let child = null;
+  const start = () => {
+    child = spawn(process.execPath, ['server.js'], { cwd: app, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    child.stdout.on('data', (d) => { log += d; });
+    child.stderr.on('data', (d) => { log += d; });
+    return child;
+  };
+  const exited = (proc) => new Promise((resolve) => proc.on('exit', resolve));
+  const api = async (p, init = {}) => {
+    const r = await fetch(base + p, { headers: { 'Content-Type': 'application/json' }, ...init });
+    return { status: r.status, body: await r.json().catch(() => ({})) };
+  };
+  const moduleIds = async () => (await api('/api/modules')).body.modules.map((m) => m.id).sort();
+
+  let failed = false;
+  try {
+    // ── 1. the move ──
+    start();
+    await waitFor(base + '/api/theme');
+    const moved = path.join(dataDir, 'modules', 'demo');
+    assert.ok(fs.existsSync(path.join(moved, 'module.json')), 'demo moved into the data directory');
+    const helper = path.join(moved, 'bin', 'demo-helper');
+    assert.ok(fs.existsSync(helper), 'its compiled helper came along');
+    assert.ok(fs.statSync(helper).mode & 0o111, 'and is still executable');
+    assert.equal(fs.existsSync(path.join(dataDir, 'modules', 'gone')), false, 'an uninstalled module is dropped, not moved');
+    assert.equal(fs.existsSync(path.join(app, 'modules')), false, "the app folder's modules/ is gone");
+    assert.deepEqual(await moduleIds(), ['demo'], 'demo runs, gone does not');
+    assert.match(log, /moved bundled module "demo" v1\.0\.0 into the data directory/);
+    assert.match(log, /the app folder carries no modules now/);
+    const state = (await api('/api/admin/state')).body;
+    assert.equal(state.modules.find((m) => m.id === 'demo')?.source, 'installed', 'demo is an installed copy now');
+
+    // The catalog sees the repo's modules/ — as offers, not as a bundle.
+    let cat = (await api('/api/admin/catalog?refresh=1')).body;
+    assert.equal(cat.shell.remote.error, '', 'the mock forge answers: ' + cat.shell.remote.error);
+    assert.deepEqual(cat.updates.map((u) => `${u.id} ${u.installedVersion}->${u.version}`), ['demo 1.0.0->2.0.0']);
+    assert.deepEqual(cat.available.map((a) => a.id).sort(), ['gone', 'other', 'third'].filter((id) => id !== 'gone'), 'other and third are on offer');
+
+    // ── 2. a shell update carries no modules ──
+    const running = child;
+    const up = await api('/api/admin/update', { method: 'POST', body: '{}' });
+    assert.equal(up.status, 200, 'update: ' + JSON.stringify(up.body));
+    assert.equal(await exited(running), 75, 'the server asks its supervisor for a restart');
+    assert.equal(fs.existsSync(path.join(app, 'modules')), false, 'the archive\'s modules/ was not written into the app folder');
+    assert.equal(JSON.parse(fs.readFileSync(path.join(app, 'package.json'), 'utf8')).version, '9.9.9', 'but the shell itself was updated');
+
+    log = '';
+    start();
+    await waitFor(base + '/api/theme');
+    assert.doesNotMatch(log, /moved bundled module/, 'nothing left to move on the second start');
+    assert.deepEqual(await moduleIds(), ['demo'], 'still just demo, from the data directory');
+    cat = (await api('/api/admin/catalog')).body;
+    assert.deepEqual(cat.available.map((a) => a.id).sort(), ['other', 'third'], 'the new modules are offers, not installs');
+
+    // ── 3. several at once ──
+    const many = await api('/api/admin/modules/install', { method: 'POST', body: JSON.stringify({ ids: ['other', 'third', 'nope'] }) });
+    assert.equal(many.status, 200);
+    assert.equal(many.body.ok, false, 'one of them does not exist');
+    assert.deepEqual(many.body.results.map((r) => `${r.id}:${r.ok}`), ['other:true', 'third:true', 'nope:false']);
+    assert.ok(fs.existsSync(path.join(dataDir, 'modules', 'other', 'module.json')), 'other landed in the data directory');
+    assert.deepEqual(await moduleIds(), ['demo', 'other', 'third'], 'and both are mounted');
+    const empty = await api('/api/admin/modules/install', { method: 'POST', body: '{}' });
+    assert.equal(empty.status, 400, 'nothing to install is said');
+
+    console.log('unbundled shell: every check passed');
+  } catch (err) {
+    failed = true;
+    console.error('FAIL:', err.message);
+    console.error('--- last of the server log ---\n' + log.slice(-2500));
+  } finally {
+    try { child?.kill('SIGTERM'); } catch { /* gone */ }
+    forge.close();
+    await new Promise((r) => setTimeout(r, 400));
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+  process.exit(failed ? 1 : 0);
+})();