MoonModules · ewowi · Aug 24, 2026 · Aug 24, 2026 · coderabbitai · Aug 24, 2026
diff --git a/docs/backlog/backlog-core.md b/docs/backlog/backlog-core.md
@@ -229,6 +229,16 @@ Two improvements when this matters:
 
 Not blocking — MoonDeck is a developer tool, not a production server. Pick this up when MoonDeck is in scope for hardening.
 
+### A tagged release does not reach the web installer until the next main deploy (bug)
+
+`deploy-pages` in `.github/workflows/release.yml` is gated `if: github.ref == 'refs/heads/main'`, because the `github-pages` environment's protection rule only allows main. The installer's release list is **staged into the Pages site at deploy time** (`install.js` self-hosts the last 5 stable + 5 prerelease releases; the release-asset URLs redirect to a host that sends no CORS header, so the browser cannot read them from the Pages origin). Together those mean **pushing a `vX.Y.Z` tag publishes the release but never updates the installer** — the new version reaches the picker only when something later pushes to main.
+
+Hit on v4.0.0 (2026-08-24): the release published at 16:15:59, a main deploy ran at 16:16 and enumerated releases *before* it existed, and the installer offered v3.0.0 as newest for hours. Re-running the workflow with the tag fixed it, and that manual re-run is the current workaround.
+
+Note the device's own OTA picker is unaffected — it reads `api.github.com` live ([app.js](../../src/ui/app.js) `RELEASES_API`), which is why a device could offer v4.0.0 while the installer could not. Two independent paths to the same release list.
+
+The fix is to let a tag deploy Pages: either relax the environment's branch protection to include tags, or have the tag release trigger a Pages deploy as a follow-on (`workflow_run`, or a repository_dispatch from the release job). Until then, every stable release needs a manual `gh workflow run release.yml -f tag=vX.Y.Z` afterwards, which is exactly the kind of remember-to-do-it step a release ritual should not carry.
+
 ### CI: pin GitHub Actions to commit SHAs (supply-chain hardening)
 
 `.github/workflows/release.yml` references all 9 action types by mutable `@vN` tag (`actions/checkout@v4`, `astral-sh/setup-uv@v3`, `softprops/action-gh-release@v2`, `espressif/esp-idf-ci-action@v1`, …). A mutable tag can be force-moved to malicious code by a compromised publisher; pinning each `uses:` to a full commit SHA (with a `# vN` trailing comment) removes that vector. **Done already (cheaper half):** `persist-credentials: false` on every checkout that doesn't push, so the `GITHUB_TOKEN` isn't left in `.git/config` for later steps to read (the `release` job keeps it — it force-pushes the `latest` tag). **Not done (this item):** SHA-pinning, because it carries an ongoing cost — pinned SHAs go stale and miss security patches, so it only pays for itself **alongside Dependabot** (or a Renovate config) to auto-bump them. Pick this up as a deliberate "CI hardening + Dependabot" pass, not piecemeal. Low risk today: every action pinned is a first-party `actions/*` or a well-known publisher (astral, espressif, softprops), not an obscure third-party action.

diff --git a/docs/backlog/backlog-light.md b/docs/backlog/backlog-light.md
@@ -122,6 +122,36 @@ projectMM already speaks DMX **over the network** (Art-Net / sACN via `NetworkRe
 
 Sequencing: it's a **driver** (`src/light/drivers/`) + a platform UART-RS485 seam + a fixture model shared with the Art-Net path — the buffer→channel encode is already done. Plan when a DMX fixture is actually on the bench and a catalog board's `supported`/`planned` list points at wired DMX. The [PinsModule pin-assignment work](backlog-core.md#pinsmodule-strict-reject-on-add-mode-the-one-remaining-increment) covers the RS485/DMX TX/RX/DE slot; this is the driver that consumes it.
 
+## Integration with other LED and visuals tools
+
+Distilled from a Discord thread with panel-card users (2026-08-24), where two people drove ColorLight walls from projectMM and described the pipelines they already run.
+
+### projectMM as a video source — NDI first, Spout/Syphon only if proven (open)
+
+Users asked for projectMM's rendered output to feed *their* tools, not the other way round. One runs OBS → Spout → his own VLAN-tagged card driver; he asked whether projectMM could be a Spout source. Input is not the gap: `NetworkReceiveEffect` already binds Art-Net, E1.31/sACN and DDP at once and answers ArtPoll, so any controller can already drive projectMM.
+
+**NDI is the recommended first implementation.** It is the AV industry's standard for video over IP, one implementation covers Windows, macOS, Linux and ARM, it discovers by name, and it crosses machines. Spout (Windows, DirectX/OpenGL) and Syphon (macOS, Metal/OpenGL) share a GPU texture zero-copy, so they are lower latency and bit-exact, but they are **same-machine only**, are **two** platform implementations, and leave **Linux and the Pi with nothing**. At LED-wall pixel counts (a 256x256 wall is 65K pixels) the latency difference is far below one frame of the render loop, so it does not decide the choice; coverage does. A Spout user is also reachable through NDI in one hop, since OBS, Resolume and TouchDesigner all speak both.
+
+**The licence shapes the design, and the shape is already established here.** projectMM is GPL-3.0 and the NDI runtime is proprietary, so projectMM must not *redistribute* it: bundling would require projectMM's own licence to carry NDI's restrictions downstream, which GPL-3 forbids. The user installs the NDI runtime themselves, exactly as they already install **Npcap** for the panel-card driver, and projectMM calls whatever is present.
+
+That is the arrangement `platform_desktop.cpp` uses for Npcap today: resolve the library with `LoadLibrary`/`dlopen` rather than linking it, declare the handful of functions with the library's own signatures rather than including its headers (so the SDK never becomes a build requirement for CI or contributors), and report the feature unavailable when it is absent instead of failing to link. Two independent installs that talk to each other, like Resolume on the same desktop.
+
+Also note projectMM renders into a CPU buffer, so a Spout/Syphon path would upload to the GPU purely to hand off, spending the zero-copy advantage it was chosen for.
+
+### Multi-card walls — does a daisy chain work today? (open, ask before building)
+
+The ColorLight format has **no card addressing**: the destination MAC is a fixed constant and every card filters on it, so every card on a segment shows the same image. A user with six cards on a switch observed exactly that.
+
+The industry-standard answer is **daisy-chaining** — a sending card's ports each drive a chain, and each card takes its region by position in the chain. That user works around it with per-card VLANs and a managed switch instead, which he built for throughput and for per-card colour-temperature grouping across mixed panel batches; he described it as his own solution, not a standard.
+
+**Establish first whether a daisy chain already works with projectMM** (one contact has a 96K daisy-chained rig). If the cards self-assign by chain position, the standard multi-card case is already solved and nothing is needed. Only if it does not work is there a feature here, and it should follow the daisy-chain standard rather than the VLAN workaround. 802.1Q tagging is technically a clean fit for a raw-L2 sender (the tag is part of the Ethernet header, the switch strips it before the card, so card firmware is unaffected), but it serves one bespoke architecture.
+
+### Smaller asks from the same thread
+
+- **Read the wall layout from the ColorLight cards.** The cards can report their configuration and at least one user's own tool already does it; it would remove the manual layout step.
+- **Per-card colour temperature and brightness**, via the ColorLight sync-packet bytes, grouped by sync group — used to colour-match mixed panel batches live.
+- **Docker image**, asked for by a user tracking updates in an IoT system. The Linux binary and `.deb` already ship, so this is packaging rather than new capability.
+
 ## Sensors and audio-reactive input
 
 ### Audio-reactive follow-ups

diff --git a/docs/history/plans/Plan-20260824 - NDI output.md b/docs/history/plans/Plan-20260824 - NDI output.md
@@ -0,0 +1,125 @@
+# Plan — NDI output: projectMM as a video source
+
+## Context
+
+Panel-card users on Discord (2026-08-24) asked for projectMM's rendered output to feed *their*
+tools. One runs OBS → Spout → his own card driver and asked whether projectMM could be a Spout
+source; another observed that OBS, Resolume and TouchDesigner all speak NDI, so projectMM could be
+an NDI source and reach a Spout pipeline through one hop.
+
+Input is not the gap: `NetworkReceiveEffect` already binds Art-Net, E1.31/sACN and DDP at once.
+What is missing is the other direction — projectMM's pixels reaching a production visuals rig.
+
+Decision recorded in [backlog-light § Integration with other LED and visuals tools](../../backlog/backlog-light.md):
+**NDI first.** One implementation covers Windows, macOS, Linux and ARM, it discovers by name, and
+it crosses machines. Spout (Windows) and Syphon (macOS) are lower latency and bit-exact but are
+same-machine only, are two platform implementations, and leave Linux and the Pi with nothing. At
+LED-wall pixel counts (a 256x256 wall is 65K pixels) the latency difference sits far below one
+frame of the render loop, so coverage decides, not latency.
+
+**Scope: output only.** NDI is bidirectional and an `NdiReceiveEffect` is a real second feature,
+but it is not this branch.
+
+## The licensing constraint, and what it dictates
+
+projectMM is GPL-3.0. The NDI runtime is proprietary and its licence requires a redistributor's own
+EULA to carry NDI's terms forward, which GPL-3 forbids. **So projectMM must not redistribute it.**
+
+This is not a blocker; it is a design constraint projectMM has already met once. **Npcap** is the
+precedent: proprietary, required for raw L2 on Windows, and
+[platform_desktop.cpp:814](../../../src/platform/desktop/platform_desktop.cpp) resolves `wpcap.dll`
+with `LoadLibrary` rather than linking it, declaring the five functions with pcap's own signatures
+rather than including `pcap.h`. The user installs Npcap; the panel-card tutorial says so; the binary
+builds and runs identically without it and reports raw send unavailable.
+
+NDI follows exactly that arrangement:
+
+- **The user installs the NDI runtime.** We bundle nothing and ship no SDK.
+- **Resolve at run time** (`LoadLibrary` on Windows, `dlopen` elsewhere), never link.
+- **Declare the needed functions with the SDK's own signatures**, never include its headers — so the
+  SDK is not a build requirement for CI or for any contributor.
+- **Degrade visibly** when it is absent (ADR 0002, allocate-and-degrade): a status line, not a
+  failure.
+
+## Design
+
+### The platform seam
+
+NDI is a host capability, so it lives behind `platform::` like every other one, and the driver never
+sees a `dlopen`. Following `hasNamedNetInterfaces`, each platform declares a `constexpr bool hasNdi`
+in its own `platform_config.h`: **true on desktop, false on ESP32** (no runtime to load, and the
+encode cost does not belong on a microcontroller).
+
+The seam is deliberately tiny — four functions, mirroring the pcap surface:
+
+```
+bool ndiAvailable();                                  // runtime present and loaded
+bool ndiSenderOpen(const char* name);                 // create a named source
+void ndiSenderClose();
+bool ndiSendFrame(const uint8_t* rgb, uint16_t w, uint16_t h, uint8_t fps);
+```
-```
-bool ndiAvailable();                                  // runtime present and loaded
-bool ndiSenderOpen(const char* name);                 // create a named source
-void ndiSenderClose();
-bool ndiSendFrame(const uint8_t* rgb, uint16_t w, uint16_t h, uint8_t fps);
-```
-```
-bool ndiAvailable();                                  // runtime present and loaded
-bool ndiSenderOpen(const char* name);                 // create a named source
-void ndiSenderClose();
-bool ndiSendFrame(const uint8_t* rgb, uint16_t w, uint16_t h, uint8_t fps);
-```
+
+`ndiSendFrame` takes a tightly-packed RGB buffer and the geometry; the platform layer converts to
+NDI's frame struct. A stub in the no-NDI build returns false from everything, which is what keeps
+`mm_tests` and every ESP32 target compiling untouched.
+
+### The driver
+
+`NdiDriver : DriverBase`, registered like the others in `main.cpp`, gated on `hasNdi` so it is
+offered only where it can run. It follows `PreviewDriver` closely, which is the existing driver that
+also turns the rendered buffer into a frame for a remote consumer:
+
+- **Controls**: `sourceName` (what appears in OBS's source list, defaulting to the device name),
+  `fps` (a ceiling, as in PreviewDriver), plus the inherited correction controls.
+- **`tick()`**: rate-limit to `fps`, read the source buffer, hand it to `platform::ndiSendFrame`.
+  `MM_NONBLOCKING`, and no allocation in the tick — the RGB staging buffer is sized in `prepare()`.
+- **`prepare()`**: size the staging buffer to the layer, open the sender, set the status. Re-runs on
+  a geometry change, exactly as `affectsPrepare` governs elsewhere.
+- **Status**, which is the whole user-facing diagnostic:
+  - no runtime → `NDI runtime not installed`
+  - open failed → the reason
+  - running → `sending <w>x<h> at <fps> fps as '<name>'`
+
+### What this deliberately does not do
+
+- **No audio.** NDI carries it; projectMM has no video-audio pairing to send.
+- **No NDI HX / compression choice.** Ship the default; add a control only if a user needs it.
+- **No receive.** Its own feature.
+
+## Steps
+
+1. **The platform seam.** Declare `hasNdi` in both `platform_config.h` files and the four functions
+   in `platform.h`. Implement the runtime load in `platform_desktop.cpp` beside the Npcap block,
+   reusing its shape. ESP32 needs no implementation (the flag is false).
+   *Tests:* the stub path — `ndiAvailable()` false with no runtime, and every call safe.
+2. **`NdiDriver`.** The driver above, registered in `main.cpp` behind the `hasNdi` gate.
+   *Tests:* controls round-trip; a prepare with no runtime reports the status and does not crash;
+   the frame conversion is pinned against a known buffer.
+3. **Docs.** A driver card in `docs/moonmodules/light/drivers.md`, and a short section in the
+   panel-cards tutorial's sibling — where to install the runtime per OS, exactly as §6.1 does for
+   Npcap.
+4. **Bench.** Install the NDI runtime and OBS with the DistroAV plugin; confirm projectMM appears as
+   a source by name and that the wall's image arrives. **This is the gate: an output path is not
+   verified until a receiver shows the frames.**
+
+## Risks
+
+1. **Nothing is verifiable without a receiver.** Steps 1 and 2 can be written and unit-tested blind,
+   but "it works" requires step 4. The plan is ordered so the untestable claim comes last.
+2. **The SDK's function signatures must be right without including its headers.** Getting one wrong
+   is a silent crash rather than a compile error — the same hazard the Npcap block carries, and the
+   reason its comment names the five functions explicitly. Take them from the SDK's public docs and
+   record where each came from.
+3. **Frame format.** NDI wants a specific FourCC and stride; a mismatched stride shows as a skewed
+   image rather than an error. Pin the conversion with a unit test.
+4. **CPU cost of the encode**, which runs on the desktop render thread. Measure before claiming a
+   frame rate; the `fps` ceiling is the mitigation.
+
+## Verification
+
+- `cmake --build build` (zero warnings) and `ctest` on a machine with **no** NDI runtime, proving the
+  degrade path is the default one CI sees.
+- The same, on a machine **with** the runtime.
+- OBS (DistroAV) on the same machine, then on a second machine, confirming the cross-machine claim
+  that chose NDI over Spout in the first place.
+- The product owner's eyes on the OBS preview.
diff --git a/docs/moonmodules/light/drivers.md b/docs/moonmodules/light/drivers.md
@@ -152,6 +152,33 @@ Origin: projectMM, on [MoonLight](https://github.com/ewowi/MoonLight/blob/main/s
 
 Detail: [technical](moxygen/PreviewDriver.md)
 
+<a id="ndi"></a>
+
+### NDI 🖥️ · video out
+
+Publishes the layer as an **NDI video source**, so OBS, Resolume, TouchDesigner, MadMapper or any other NDI receiver can pick projectMM up by name — on this machine or another one on the network. Where the Preview driver draws the lights for a person, this hands the same frame to a production tool as video.
+
+The grid's `physicalWidth` × `physicalHeight` becomes the frame; each light is one pixel, with the driver's own output correction applied so a receiver sees what the wall sees.
+
+**Desktop only.** The NDI runtime is a desktop library with no microcontroller build, so the driver is offered on macOS, Windows and Linux and not on an ESP32.
+
+**You install the runtime; projectMM never ships it.** projectMM is GPL-3.0 and the NDI runtime is proprietary, so it is loaded on demand and never bundled — the same arrangement as Npcap for the [Panel Card](#panelcard) driver. Without it the driver simply reports `NDI runtime not installed`; nothing else changes.
+
+- **macOS** — install [NDI Tools](https://ndi.video/tools/) (free). It ships the runtime inside its app bundles rather than system-wide, which projectMM knows to look for. A Resolume install also carries one.
+- **Windows** — the [NDI Tools](https://ndi.video/tools/) or SDK installer puts `Processing.NDI.Lib.x64.dll` on the PATH.
+- **Linux** — install the NDI SDK; projectMM looks for `libndi.so.5`, `libndi.so.6` and `libndi.so`.
+
+To watch the output you need a receiver: **NDI Video Monitor** (part of NDI Tools) is the simplest, and OBS gains an "NDI Source" via the [DistroAV](https://github.com/DistroAV/DistroAV) plugin.
+
+- `sourceName` — the name a receiver lists. Blank uses the device's own name.
+- `fps` — frame-rate ceiling (default 30, 1–120). NDI paces the receiver from this.
+
+Status tells you where you are: `NDI runtime not installed` (install it), `could not create the NDI source` (the runtime is there but refused), or `sending <w>x<h> at <n> fps` when it is live.
+
+Origin: projectMM, against NewTek/Vizrt's documented NDI C API
+
+Detail: [technical](moxygen/NdiDriver.md)
+
 ## LED driver — details
 
 **Which driver?**