Module rules: a native helper ships prebuilt, for Apple silicon and Windows

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 the catalog
delivers exactly the folder that is in the repo — so a module's native
program (audio capture, a decoder) ships already built, inside the module
folder, one file per platform: bin/<name>-macos-arm64 and
bin/<name>-win-x64.exe are required, Intel macOS optional, source and the
script that rebuilds every binary under native/.

The guide's rule 3 now says so, "The shape of a module" shows the layout,
and a new "Native helpers" section gives the contract: pick the binary by
platform at runtime, report the feature off when there is none — never
build, never search the machine, never ask the operator to install
anything — one command-line contract in any language per platform, bump
the version when a binary changes, keep them lean, sign the macOS one.
CLAUDE.md carries the one-line version. Rules only: no module changes here.

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

CLAUDE.md

@@ -28,7 +28,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

@@ -325,8 +325,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:
-  **Plan** (the order of service) and **Teams** (who is scheduled).
+- **PCO Plan** — Planning Center Services, as three tiles in the ＋ picker:
+  **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,
@@ -357,6 +358,16 @@ below. Nothing is installed without someone clicking.
   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,6 +86,10 @@ 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>/
 ```
 
@@ -97,6 +104,66 @@ the newer version runs. **Uninstall** in the admin page removes an installed
 module's files (a bundled one is hidden instead, since its folder belongs to
 the app); 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
 
 ```json

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
-   tile (picker entry "teams") is built by teams-client.js, everything below
-   draws the Plan tile.
+   The module presents three tiles and this is the entry for all of them: the
+   Teams tile (picker entry "teams") is built by teams-client.js and the Song
+   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 });
 }
 
@@ -367,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')) {

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.8.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"
   ],
@@ -621,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/style.css

@@ -206,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);
@@ -635,25 +637,110 @@
 
 [data-module="pco-plan"] .pp-abs-sec {
   flex: none;
-  padding: 0.1em 0.5em;
-  border-radius: 999px;
-  border: 1px solid var(--border);
+  /* 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;
+  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) 40%, transparent) var(--pp-sec-fill, 0%),
-      transparent var(--pp-sec-fill, 0%));
+      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; }

package.json

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

server.js

@@ -910,21 +910,9 @@ async function fetchArchive() {
     signal: AbortSignal.timeout(30000),
     headers: { 'User-Agent': `ProdDash/${SHELL_VERSION}` },
   });
-  const where = `${REPO.owner}/${REPO.repo}@${REPO.branch}`;
-  // A forge that wants a sign-in does not refuse: it redirects the download
-  // to its login page, which arrives as a 200 of HTML. Say that, not
-  // zlib's "incorrect header check".
-  if (res.redirected && /\/user\/login\b|\/login\b/.test(new URL(res.url).pathname)) {
-    throw new Error(`${FORGE.base} requires a sign-in to read ${where} — turn off "require sign-in to view" in Gitea, or make the repo readable without one`);
-  }
-  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${where}`);
+  if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${REPO.owner}/${REPO.repo}@${REPO.branch}`);
   const gz = Buffer.from(await res.arrayBuffer());
   if (gz.length > MAX_ARCHIVE_BYTES) throw new Error('archive is unexpectedly large');
-  if (gz.length < 2 || gz[0] !== 0x1f || gz[1] !== 0x8b) {
-    const type = String(res.headers.get('content-type') || 'unknown type').split(';')[0].trim();
-    const looksHtml = /^\s*<(!doctype|html)/i.test(gz.subarray(0, 64).toString('utf8'));
-    throw new Error(`${FORGE.base} answered with ${looksHtml ? 'a web page' : type} instead of the ${where} archive — check the forge address and that the repo is readable without a sign-in`);
-  }
   const { files, comment } = parseTar(zlib.gunzipSync(gz));
   const stripped = new Map(); // drop the archive's single top-level folder
   for (const [p, data] of files) {

tools/update-check.test.js

@@ -1,176 +0,0 @@
-'use strict';
-
-/**
- * The update check against a forge that misbehaves: the admin page must say
- * what went wrong in words, never zlib's "incorrect header check".
- *
- *   node tools/update-check.test.js
- *
- * Plain Node, no dependencies. Starts a mock forge whose answer to the
- * branch-archive download can be switched at runtime, starts server.js on a
- * spare port pointed at it, and reads the shell status the admin page shows
- * after each kind of answer:
- *
- *   - a Gitea that requires a sign-in redirects the download to its login
- *     page (a 200 of HTML) — the case that hit both booths on 2026-09-29;
- *   - a captive portal or a wrong address answers HTML outright;
- *   - a plain HTTP error;
- *   - and a real archive, which must still parse and offer the update.
- *
- * Exits non-zero on the first failure and always stops what it started.
- */
-
-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 ROOT = path.join(__dirname, '..');
-
-function freePort() {
-  return new Promise((resolve, reject) => {
-    const probe = net.createServer();
-    probe.listen(0, '127.0.0.1', () => {
-      const { port } = probe.address();
-      probe.close(() => resolve(port));
-    });
-    probe.on('error', reject);
-  });
-}
-
-async function waitFor(url, ms = 15000) {
-  const deadline = Date.now() + ms;
-  let last = '';
-  while (Date.now() < deadline) {
-    try {
-      const r = await fetch(url);
-      if (r.ok) return;
-      last = 'HTTP ' + r.status;
-    } catch (err) {
-      last = err.message;
-    }
-    await new Promise((r) => setTimeout(r, 200));
-  }
-  throw new Error('server did not come up: ' + last);
-}
-
-/** A branch archive the way a forge would build one: one top-level folder. */
-function buildArchive(dir) {
-  const top = path.join(dir, 'ProdDash-main');
-  fs.mkdirSync(path.join(top, 'modules', 'demo'), { recursive: true });
-  fs.writeFileSync(path.join(top, 'package.json'), JSON.stringify({ name: 'proddash', version: '9.9.9' }));
-  fs.writeFileSync(path.join(top, 'modules', 'demo', 'module.json'), JSON.stringify({ id: 'demo', name: 'Demo', version: '1.0.0', client: 'client.js' }));
-  fs.writeFileSync(path.join(top, 'modules', 'demo', 'client.js'), 'export default function () {}\n');
-  const out = path.join(dir, 'main.tar.gz');
-  execFileSync('tar', ['-czf', out, '-C', dir, 'ProdDash-main']);
-  return fs.readFileSync(out);
-}
-
-(async () => {
-  const work = fs.mkdtempSync(path.join(os.tmpdir(), 'proddash-update-test-'));
-  const dataDir = path.join(work, 'data');
-  fs.mkdirSync(dataDir);
-  const archive = buildArchive(path.join(work, 'forge'));
-
-  // ── the mock forge ──
-  let mode = 'ok';
-  const LOGIN_PAGE = '<!DOCTYPE html>\n<html><head><title>Sign in</title></head><body>Sign in to continue</body></html>';
-  const forge = http.createServer((req, res) => {
-    const url = new URL(req.url, 'http://forge.invalid');
-    if (url.pathname === '/user/login') {
-      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-      return res.end(LOGIN_PAGE);
-    }
-    if (url.pathname !== '/michael/ProdDash/archive/main.tar.gz') {
-      res.writeHead(404, { 'Content-Type': 'text/plain' });
-      return res.end('not here');
-    }
-    switch (mode) {
-      case 'login-redirect':
-        res.writeHead(303, { Location: '/user/login?redirect_to=' + encodeURIComponent(url.pathname) });
-        return res.end();
-      case 'html':
-        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-        return res.end('<html><body>You must log in to this network first</body></html>');
-      case 'notfound':
-        res.writeHead(404, { 'Content-Type': 'text/plain' });
-        return res.end('no such branch');
-      default:
-        res.writeHead(200, { 'Content-Type': 'application/gzip' });
-        return res.end(archive);
-    }
-  });
-  const forgePort = await freePort();
-  await new Promise((r) => forge.listen(forgePort, '127.0.0.1', r));
-  const forgeBase = `http://127.0.0.1:${forgePort}`;
-
-  // ── ProdDash, pointed at it ──
-  const port = await freePort();
-  const child = spawn(process.execPath, ['server.js'], {
-    cwd: ROOT,
-    env: {
-      ...process.env,
-      PRODDASH_DATA_DIR: dataDir,
-      PORT: String(port),
-      PRODDASH_FORGE: forgeBase,
-      PRODDASH_REPO: 'michael/ProdDash',
-      PRODDASH_NO_REMOTE_CHECK: '1',
-      PRODDASH_LAUNCHER: '1',
-    },
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-  let log = '';
-  child.stdout.on('data', (d) => { log += d; });
-  child.stderr.on('data', (d) => { log += d; });
-  const base = `http://127.0.0.1:${port}`;
-
-  /** What the admin page shows after a forced check. Admin is open: a fresh data dir has no PIN. */
-  const check = async (m) => {
-    mode = m;
-    const r = await fetch(base + '/api/admin/catalog?refresh=1');
-    assert.equal(r.status, 200, `catalog: HTTP ${r.status}`);
-    const body = await r.json();
-    return body.shell;
-  };
-
-  let failed = false;
-  try {
-    await waitFor(base + '/api/theme');
-
-    let shell = await check('login-redirect');
-    assert.match(shell.remote.error, /requires a sign-in/, 'a login redirect is named as such: ' + shell.remote.error);
-    assert.match(shell.remote.error, /require sign-in to view/, 'and the Gitea setting to look at is named');
-    assert.doesNotMatch(shell.remote.error, /header check/, 'never zlib\'s words');
-    assert.equal(shell.updateAvailable, false);
-
-    shell = await check('html');
-    assert.match(shell.remote.error, /answered with a web page instead of the michael\/ProdDash@main archive/, shell.remote.error);
-
-    shell = await check('notfound');
-    assert.match(shell.remote.error, /HTTP 404 fetching michael\/ProdDash@main/, shell.remote.error);
-
-    shell = await check('ok');
-    assert.equal(shell.remote.error, '', 'a real archive clears the error: ' + shell.remote.error);
-    assert.equal(shell.remote.version, '9.9.9', 'and is read');
-    assert.equal(shell.updateAvailable, true, 'and offered');
-
-    // Back to a broken forge: the last good read is not mistaken for a current one.
-    shell = await check('login-redirect');
-    assert.match(shell.remote.error, /requires a sign-in/);
-
-    console.log('update check: every check passed');
-  } catch (err) {
-    failed = true;
-    console.error('FAIL:', err.message);
-    console.error('--- last of the server log ---\n' + log.slice(-2000));
-  } finally {
-    child.kill('SIGTERM');
-    forge.close();
-    await new Promise((r) => setTimeout(r, 400));
-    fs.rmSync(work, { recursive: true, force: true });
-  }
-  process.exit(failed ? 1 : 0);
-})();