# AGENTS.md — LivePremier Plus
Orientation for an LLM or a newcomer picking this up cold. [README.md](README.md)
is the *what*; this is the *why* and the traps.
## The one-paragraph version
A local reverse proxy that adds panels to Analog Way's own Web RCS — on a
LivePremier, and on a Midra 4K or Alta 4K for the panels that platform can
carry: a programmer that saves memories without touching a bus, a VPU resource
map, a command line, a theatre-style cue stack, the memory banks and layer
properties in windows of their own, layer groups, routing through external
matrices, a Bitfocus Companion mounted on the same origin, and the rest the
README lists. You point it at a switcher and browse to it instead of to the
device. It does not replace the vendor UI and does not ship a theme — it borrows
the vendor's stylesheet — and **everything it shows comes off the vendor's own
socket**. The server opens AWJ itself only for one-shot exchanges (OSC input,
the Pixelhue panel, a typed AWJ line, the memory import and export) and never
to mirror state; "Why a proxy" below says why that line is the one that matters.
**It was a Chrome extension until 0.2.0.** The panels, the store mirror and the
cue engine are unchanged; what went away was `manifest.json`, the isolated-world
loader and the `chrome.storage` broker. Read "Why a proxy" below before
proposing to bring any of that back.
## The four ideas everything else follows from
**1. Light DOM, not shadow DOM.** The vendor stylesheet defines about 500 `aw-`
utility classes — a slate-grey scale, spacing, typography, cards, shadows.
Rendering into the page's light DOM means the panels inherit all of it for free
and stay correct when the vendor restyles. A shadow root would have isolated us
from the one thing we want. Reach for an `aw-` class first; `ui/theme.js` is
only for structure the vendor system has no name for.
**2. Nothing about the vendor's markup is stable, so nothing is hard-coded.**
Web RCS is built with CSS modules: every component class carries a per-build
hash (`sidebar-module__c__menu___1sHvq` today, something else next firmware).
The sidebar entries are therefore **cloned from a real one at runtime** and then
rewritten, including the active-state classes, which are lifted off whichever
item is currently active. Icons come from the page's own SVG sprite by id.
**3. Ride the app's socket; never open a second one.** The device counts its
clients and shows the count in the header, and AWJ's separate five-client budget
is small. A passenger connection would show up as a phantom operator. This is
why the hook has to wrap `WebSocket` before the vendor bundle constructs one —
there is no later opportunity. The proxy inlines it into `
`, and since
every vendor script tag is `defer`, the parser orders it first. As an extension
this was a `document_start` content script, which usually won that race but was
never promised to.
The browser's own socket is relayed **byte-for-byte** to the device, so this
process never has to understand WebSocket framing, and exactly one connection
reaches the box per tab.
**4. `core/` knows nothing about browsers.** No DOM, no transport. It imports
and runs under plain Node, which is what the tests do. The browser panels are
one front-end; a standalone AWJ client is meant to be another and should need
only a new `transports/` module. Keep device I/O out of `core/`. A plugin
keeps the same rule inside its own folder: the file both its halves import
(`plugins/companion/core.js`) has no I/O either.
## Plugins: what the app is made of
Every feature is a **plugin**, described once in `src/core/plugins.js`,
switchable in Preconfig ▸ LivePremier Plus → Plugins, and living in
`plugins//` with a server half and/or a page half, loaded by
`server/plugin-host.js` and `src/ui/plugin-host.js` exactly as a plugin written
elsewhere is ([docs/PLUGINS.md](docs/PLUGINS.md)). **None is wired in by hand
any more**: `src/main.js` is the shell, the tab strip, the settings page and the
plugin loader, and `server/proxy.js` the relay, the setup page, settings,
`/awj`, `/addresses` and the plugin host. A new feature is a new folder in
`plugins/`, not an edit to either.
A built-in may import `src/` directly, and shared engines and components stay
in `src/` where every plugin can reach them (`core/vpu.js`, `core/patch.js`,
`ui/stage.js`, `ui/properties-panel.js` — the Layer tab and the Edit page both
draw it — and the vendored models). **Never import another plugin's folder**:
its files are only served while it is on, and one switched off would take the
importer down with it. Share through a service instead. A plugin's card on the
settings page is `ctx.ui.settingsSection` — Pixelhue's is the example. A panel
that pops out does it into a page in its own folder (`popout.html`, served by
the host) that boots through `ui/popout.js` — Memories' is the whole of one.
**Features extend each other through `core/contributions.js`, never by
name.** The cue engine had Matrix Routing's two actions in its switch, the
Console intercepted `/lp/matrix/` by hand, and the OSC server took a hook only
the router could use — three special cases no other plugin could have. Now the
engine asks for a `cueAction` by kind, the OSC server and the Console for an
`oscAddress` by prefix, the setup file for each `configSection`, and Matrix
Routing contributes all three from its own folder, exactly as anybody's plugin
would. Do not put a feature's name back into
`cuestack.js`, `osc.js` or the Console's `panel.js`: if a feature needs a new kind of
hook, add a point to `POINTS`, with the rules that stop one plugin taking
another's — or the switcher's — over. Shared state goes the same way:
`provide`/`use`, the cue stack being `use('stack')`.
What the hosts own, so a plugin does not have to: routes under
`/__lpp//…`, server-sent streams, relayed sockets, and disposal of all of
it when the plugin is switched off — live, with no restart, on the server; on
the next load in the page. A plugin that throws while starting is marked failed
and says why on its settings row; nothing else goes down with it.
The things about it that break quietly:
- **Importing a server half must do nothing.** The host imports every hosted
plugin at startup, switched on or not, to read its settings schema.
Everything with an effect belongs in `activate(ctx)`.
- **A plugin's settings live in `plugins..settings`, never at the top
level.** Companion's three fields used to be top-level, and so did the Edit
page's and OSC input's; each schema's `legacy` list lifts them wherever they
still appear (an old `settings.json`, an old setup file, a caller sending
the old shape), and a lifted value wins. A settings save merges `plugins`
one level deeper, so a switch never wipes a plugin's settings, and the host
tells a running plugin about a change only when its own schema's `changed`
says so — or a Companion address change would rebind the OSC socket.
- **`plugins/` must be in every package.** The app runs without a missing
plugin — right for a user's folder, wrong for a release — so a Dockerfile or
`launcher/scripts/prepare.sh` without it ships features quietly absent.
`test/packaging.test.js` reads both.
- **A panel with an iframe renders in place.** See the invariant below.
- **The page loads plugins from `/__lpp/plugins`, not from the manifest
table**, so what it shows is what the server actually started.
- **A user plugin's code never runs before it is switched on.** User plugins
(`/plugins//`, validated by `validateManifest`) are found at
startup but imported only in `startPlugin`. Their settings schema therefore
arrives late: the proxy re-normalises after every `host.sync`, and the host
judges "changed" on schema-read settings, so the defaults that fill in are
not a change. Do not "simplify" discovery into importing — a test counts
imports.
- **A plugin may ask for a repaint before the sidebar exists.** A page half
that loads its data as it starts repaints when the data lands, which can be
while later plugins are still loading — so `main.js` declares `shell` and
`tabs` before `refresh` and skips a repaint until both are built. With them
as `const` further down, that repaint was a ReferenceError; found when Layer
Groups moved.
- **A built-in's `ctx.storage` writes the files the app always wrote.**
`names-.json` beside the stacks, keyed by `safeDeviceKey` from
`server/storage.js` — the same function `StackStore` uses — so moving a
feature into a plugin moves nothing on disk, an older build still reads it,
and `server/config-file.js` finds it where it always did. The per-switcher
`{ data }` route every per-switcher document shares (layer names, groups,
locks, pixel maps, surfaces, UMDs) is `server/documents.js`. A user plugin's
documents go in `/plugin-data//`, never its code folder, which
the page is served from.
- **`examples/plugins/hello-switcher` is tested as a user plugin**, unchanged,
through the host and through a real data directory. If the API moves, the
example moves with it, or the suite says so.
- **A cue action is not awaited, and runs ahead of the take.** A contributed
`run` goes out with the recalls; the take is deferred behind them. Awaiting
it would let one slow router hold a take hostage, and it is the reason
routing before a take works at all. A cue naming a kind nobody handles
keeps the action and warns when it fires — never drop it, it is somebody's
show file.
- **Experimental means behind a switch, not shipped quietly.** What the
switcher accepts but no frame has been seen to do goes behind the
Experimental features plugin (`plugins/experimental/`, off by default): a
plugin of its own sets `experimental: true` and requires it, and the
Plugins card leaves it out while the switch is off; a corner of an existing
plugin asks for the `experimental` service per use, and behaves exactly as
before without it. Nothing behind it goes in the README or the guide until
a frame has shown what it does; NOTES.md says what has been run.
## Why a proxy, and the three things that make it work
Do not "simplify" any of these; each is load-bearing and each was verified.
- **Inject into the document, never rewrite URLs.** Every vendor asset path is
root-absolute, so path-preserving proxying needs no rewriting. The hashes
change every firmware; a rewriter would be a permanent maintenance tax on a
bundle nobody controls.
- **Only `text/html` is ever buffered** — and the source thumbnails the vendor
polls, which `server/snapshot-keeper.js` holds whole so it can hand them out
again (148 KB on a C mini; anything over 8 MB is passed on, not kept).
Everything else streams. `GET /api/stores/device` is over 100 MB —
collecting it would be absurd, and it is not a document anyway.
- **Framing headers must be rewritten together.** The device serves documents
**chunked**. Re-sending one whole means dropping both `transfer-encoding` and
`content-encoding` and setting `content-length`; keeping `transfer-encoding`
alongside a `content-length` is illegal and strict clients reject it outright.
This shipped as a bug and was caught by a test, not by looking at it.
**There is now an AWJ path in the server, and the old argument still stands.**
`server/awj.js` opens TCP 10606. Read this before touching it, because the
reason it is allowed is narrow.
The original argument was: the store is already mirrored and stays current from
the vendor socket, so **an AWJ reader would be a second source of truth for the
same VPU state**, and two sources that can disagree about what is on air is not
worth a faster first paint. Every word of that is about *reading state into the
mirror*, and it is still correct.
What was added is not that:
- **Nothing in it ever touches the store mirror.** A reply goes back to whoever
asked and is then forgotten. The mirror still has exactly one source.
- **It holds no connection and subscribes to nothing.** One socket per
exchange, opened and closed — the device allows five clients and counts them.
- **Both callers need something the mirror cannot give.** A typed
`{"op":"get",…}` wants what the *device* says right now, in the protocol's own
spelling; answering from the mirror would be answering a question about the
device with our own opinion of it. And the OSC listener has to work with no
browser open at all, which is the entire point of a show-control input.
If you are about to make it hold a connection open, subscribe to anything, or
write into the store mirror, the original argument applies to you and you have
to beat it.
**The switcher is chosen at runtime, not at startup.** That is what lets the
desktop launcher be the fleet's stock shell with no fork: it injects a host and
a port like every other one, and the device is picked on the setup page and
remembered. It also means re-pointing at a backup frame costs a form submission
rather than a restart — and re-pointing **hangs up the existing relays**, so a
page cannot go on driving the box the operator thinks they have left.
## Arithmetic in vendor fields (`plugins/arithmetic/math-fields.js`)
Three things here are load-bearing and were each verified on a running Web RCS
rather than reasoned about:
- **The selector is `input[type=text]` with a `step` attribute.** Web RCS's
numeric fields are *text* inputs carrying `min`/`max`/`step` — geometry
reports `step="1"`, X spans -960..2880, width 0..8192. Using the vendor's own
declaration avoids matching a per-build class hash, and excludes labels and
the `00:01.000` transition field, neither of which has a `step`.
- **A bounded `type="number"` field is text only while focused.** A number
input discards what it cannot parse: after `1080-80` the browser reports
`value === ""` with `validity.badInput`, and `selectionStart` is `null`. On
6.1.x the geometry fields are number inputs (`step`/`min`/`max`), so one is
made `type=text` on `focusin` and put back on `focusout`. That costs no
stepping only because they are aw-ui's `AwNumberInput`, which steps in
script — and which 6.2 itself renders as text for its own arithmetic.
⚠️ While it is text the vendor must never be handed a string its number
input could not hold: Enter goes through only on a number, blur empties
anything else first. Do not "simplify" by holding back the `input` events
instead — React's controlled update then writes the stale number over the
typing. Unbounded number inputs and our own `wru-input`s are not swapped.
Read the 6.2.73 bundle and 6.1.60's own `AwNumberInput` (hard-coded
`type: "number"`; arrows, wheel and Enter→blur→parse all in script), and
proven on both simulators; not yet on a 6.1.x box.
- **Capture phase on `document` is the entire timing strategy.** React attaches
its handlers at the root container, so a capture listener on `document` runs
before them. We rewrite the value, then let the event continue into the
vendor's own commit handler.
Writing takes the controlled-input dance: React overrides `value` on the
element, so use the native setter from `HTMLInputElement.prototype` and then
dispatch a bubbling `input` event, or React's state never learns about it.
Verified end to end — `1080-80` in a width produced `sizeH=1000` on the wire,
with the vendor's aspect lock sending `sizeV` alongside it, exactly as if the
number had been typed.
**Never put `eval` or `new Function` in this path.** `core/expr.js` is a
recursive-descent parser over a closed token set and must stay one. It refuses
rather than guesses — division by zero is rejected specifically because
`Infinity` would survive the clamp and land as the field's max, which is a
plausible-looking wrong answer.
## Variables (`plugins/variables/`, `core/expr.js`, mynah's `variables.ts`)
`$name` is a **system** variable, read off the store mirror; `@name` is a
**user** one, defined in the panel and kept per switcher. One resolver shape,
`resolve(name, kind) → {ok, value} | {ok: false, error} | undefined`, serves
mynah (`vars` in the run context), `core/expr.js` (`evaluate(text,
{ resolve })`) and the OSC listener, so the Console, the fields and a packet
agree to the digit. `docs/VARIABLES.md` is the namespace.
The things that break quietly if "simplified":
- ⚠️ **A role variable mid-take is an error, not the old letter.**
`$S1.PGM.L2.x` goes through `presetBanks()` and refuses while `settled` is
false — the Layer panel's rule, for the Layer panel's reason.
- ⚠️ **The catalogue is walked, not listed, and only allocated layers are in
it.** `dialect.fittedLayers` gates the layers (the preset carries geometry
for every slot); `listDestinations` gates the destinations; an unreported
canvas is not given the 1920×1080 a card falls back to. Do not add a table of
store leaves — the catalogue grows with the rig because it is generated.
- **The page's index of names is cached for 250 ms**; the values never are —
every `read()` goes to the store. Hold a `resolver()` for one evaluation.
- **Cycles are found before evaluating** (Tarjan, `findCycles`), so the
recursion in `createUserEvaluator` always ends. A definition that does not
evaluate is *kept* and reported, like a spreadsheet cell; a rename rewrites
`@old` in the other definitions.
- **Mynah resolves variables in its parser**, not its compiler: a range cannot
be expanded or range-checked before its ends have values, and only a parse
error carries a span. Arithmetic lives in brackets because outside them
`+`/`-` are the range operators — `Screen 4 - 1` must keep meaning what it
meant. `test/expr.test.js` checks `core/expr.js` and mynah's
`evaluateExpression` agree case for case; they are two implementations of
one grammar on purpose (this repo's field arithmetic predates the vendored
one) and that test is what keeps them one grammar.
- ⚠️ **The OSC listener has no store, so `$` is refused there**, and so is an
`@` that reaches one (`storelessResolver`). Same asymmetry as
`preview`/`program`, and `docs/OSC.md` says so in prose generated from
`tools/gen-osc-docs.mjs`.
- **Every caller asks for the service per use** (`ctx.use('variables')`), and
falls back to exactly its old behaviour when it is null: a field with `$` in
it is left as typed, a Console line is refused naming the plugin. Field
arithmetic only flashes a refusal while a resolver exists, so switching the
plugin off restores the old silence.
- **Reads only** — it is on by default for that reason. If it ever grows a
write (a variable that sets something), it becomes a preview behind
`OFF_UNTIL_TESTED` like every other plugin that acts by itself.
Proven on the 6.2.73 simulator through the demo (2026-10-06): the panel, the
catalogue (446 names), adding, renaming, a cycle reported and broken, an armed
delete, persistence across a reload and into the setup file's `show`, the
Console's preview tags and a `Set` with variables compiling to the right four
writes (sent into a catcher, not the switcher), and a field of ours carrying
the real capture-phase listener turning `$S1.width/2 - @gap` into `920` and
refusing `$S1.widht` with the amber flash. **Not** driven: a vendor numeric
field (no layer was selectable without committing a write to the shared
simulator), the popped-out Console's Variables shelf (the Browser pane opens a
popout in place of its opener, so it has no session), a real Midra (the
catalogue is tested against a cut of the Midra 4K simulator's store), and any
hardware.
## Where our surfaces live, and why
### Four command languages, one command line
The Console takes Mynah, raw AWJ, raw Web RCS store JSON and OSC. All four come
out of `src/vendor/mynah-lang.mjs` — the same vendored build that has always
supplied the grammar — so this repo still states no grammar of its own. The
panel picks a route and nothing else.
Three things about it are load-bearing:
- **Detection is by shape, and the verdict is shown as you type.** A line read
as the wrong language produces an error about a *character* rather than about
a command, and an operator reads that as their own typo. The chip beside the
feedback says what the line is being read as, before Enter, and the log keeps
it on every row — the question "why did that not do what I meant" is usually
asked about a line several commands back.
- **A language prefix must never collide with a Mynah keyword.** `STORE` was an
alias for `JSON` upstream for one commit and turned every `Store Master 12`
into a JSON parse error, silently. Mynah's `dialects.test.ts` pins it; the
fix belongs there, not here.
- **Almost everything still rides the vendor's socket.** `Path` holds both
spellings of one address, so a typed AWJ message converts to a store write
and lands at the identical node. Only two cases take `POST /__lpp/awj`: the
operator chose the real-socket transport, or the line contains a `get`, which
the vendor socket cannot answer because it carries changes rather than
answers.
⚠️ **`preview` and `program` need the device's take state.** The Console can
resolve them — the page has the store mirror, through `presetBanks()` in
`core/screens.js`. The OSC listener cannot, and refuses those addresses with
that reason rather than guessing. A layer move landing in whichever buffer
happened to be live is the exact failure being defended against. That asymmetry
is intended and is documented in `docs/OSC.md`. **`$` variables follow the
same line**: answered at the Console, refused over UDP.
### External matrix routing (`plugins/matrix-routing/routers/`, `core/patch.js`)
The only subsystem here that talks to something other than the switcher, and
the reasoning that makes that allowed is narrow — read it before extending.
**It holds connections open, and `server/awj.js` forbids exactly that.** That
prohibition is about the *store mirror*: an AWJ reader would be a second source
of truth for state the vendor socket already carries. None of it applies to a
router, because a router is not in the store at all. There is no mirror to
contradict, nothing else in this process or the page knows what a Videohub is
routing, and its crosspoints change without us — a poll-on-demand grid would be
right when the panel opened and wrong thereafter. The five-client budget
`awj.js` respects is a limit on the Analog Way frame, not on a Videohub.
Four things are load-bearing:
- **The direction inverts.** A switcher input hangs off a router OUTPUT; a
switcher output arrives at a router INPUT. An entry stores the switcher side
only and derives the router side, because a stored direction is a stored
opportunity to disagree with the side it belongs to.
- ⚠️ **Everything counts from 1 except the Videohub wire, which counts from 0.**
`plugins/matrix-routing/routers/videohub.js` is the only file that knows this, and the
conversion is in two marked places — the same containment `core/paths.js`
gives the AWJ spelling. Getting it wrong routes a real crosspoint one off
from the one asked for and looks plausible doing it.
- **No driver writes its own state.** `route()` sends and returns; every field
comes from what the router said. A Videohub answers a refused route with ACK
and the unchanged routing, so a refusal is indistinguishable from a command
that never arrived except that the state does not move.
- **A send adds and never takes away.** A router output always shows
*something*, so "removing" a destination would mean choosing a different
source for it, and there is no answer to which.
- **A placeholder is the one driver that writes its own state** — there is no
router to ask, so it *is* the router. It is a size and a table, never a
protocol emulator. Its **plan** is only the crosspoints taken on it (never the
factory N-from-N table, which would overwrite every output on the real
frame). Going live keeps the router id, so the patch carries over; nothing is
sent on connect, and Push plan sends only what differs and names what does
not fit. A save that omits `model`/`inputs`/`outputs`/`plan` keeps the held
ones (`keepPlanning` in the plugin's server) — the panel saves from
`describe()`, which does not carry them.
⚠️ **The OSC addresses are ours, not mynah's** — the one exception to "this repo
states no grammar of its own". Mynah is the single statement of the
*switcher's* grammar; a router in front of it is not the switcher. They live in
`core/patch.js`, and the Console posts them to the launcher rather than
resolving them in the page, so the typed and the UDP paths cannot drift.
⚠️ **The Lightware and Turtle AV drivers have never spoken to hardware.** They
are written from vendor documentation, their command strings are collected in
one table per file so a correction is one edit, and they parse defensively
because that is an admission of uncertainty rather than belt and braces. The
LW3 half is polled *as well as* subscribed for the same reason. `docs/MATRIX.md`
has a procedure for proving each on real kit.
**The Router tab and box (`plugins/matrix-routing/router-box.js`) write into vendor pages**, so
they carry the same fragility as `plugins/layer-names/labels.js`: Setup ▸ Inputs/Outputs
detail pages get a tab on their **routed** strip (every anchor has an `href`,
which is why `ui/tabs.js` never claims it), and Preconfig ▸ Inputs/Outputs get
a box in the column headed `In5` / `Out5`. Which socket a page is about comes
from the URL or that heading only — `connectorForPage` is the one place, and a
page it cannot place gets nothing. The port model both the grid and the list
draw from is `choicesFor` in `core/patch.js`, so the two cannot disagree.
`routerBoxes.describe()` on `window.__WRU` reports what was found.
⚠️ **Inputs and outputs are keyed differently in the same store** — `IN_5` and
`5`, with `physical` spelled `IN_9` and `5` — and `IN_1` names both logical
input 1 and the first input card depending on the field. `core/connectors.js`
absorbs it; nothing above it should learn it. `slot` repeats within a card, so
(card, slot) is never an identity — `physical` is.
⚠️ **A Midra or Alta is a third spelling**: `INPUT_5` and `5` (plus `MTVW`),
**no `mapping` at all**, and `status/pp/isAvailable` as the gate; an input is
named and typed by its active plug (`status/pp/plug`), an output by every plug
not `NOT_AVAILABLE`. Each dialect's `connector(side, node)` reads its own
platform; `readConnectors` walks the list and knows neither. Until 2026-10-06
the LivePremier reading was applied there and found no inputs, so a HyperDeck
could not be linked on a Midra. Matrix Routing is still **not offered** on
mng (no mng probe): `connectorForPage` builds LivePremier keys from
LivePremier pages, and Midra's pages have not been read for it.
### HyperDecks (`plugins/hyperdeck/`) — never met a real deck
Blackmagic HyperDecks and anything that answers their TCP 9993 protocol; Mitti is the reference,
both as a deck (its HyperDeck emulation: plays, never records — a *profile*, not a special case)
and as the rule set (its ATEM integration: play on program; pause, rewind or next when taken off;
take or cut at a clip's end). `docs/HYPERDECK.md` is the design and the proving procedure.
- **The rules run in the page, not the server**, because the page has the store and the server
must not grow a mirror. One page holds a lease (`POST /__lpp/hyperdeck/runner`, the Pixelhue
panel's pattern); a page that takes the lease primes `prev` and acts only on later changes, so a
reload never plays a deck already on air. Do not "fix" this by subscribing on the server
without beating `awj.js`'s argument in writing.
- **On air includes the arriving buffer while a transition is unsettled** (`airState` in
`core.js`), so a deck rolls as the take starts.
- **A clip end is inferred**: the transport stopping by itself, or the clip id moving on while
playing — unless we sent a stop or goto in the last 1.5 s (`lastOurs` in `link.js`). The lead
time is the page's, off the streamed countdown; both paths fire once per `run`.
- **`slot info` is asked by number** (`slotQuery` in `protocol.js`), once the transport has
named the slot. A real Mitti 2.8.19 sends nothing back to a bare `slot info`, and with one
command in flight that cost every connect `REPLY_TIMEOUT_MS`. The sim's `--mitti` mode does the
same, and `test/hyperdeck.test.js` fails if the link goes back to the bare form.
- `tools/hyperdeck-sim.mjs` is the only deck anything here has spoken to.
### Dante (`plugins/dante/`) — **preview**, never met a real Dante device
The Dante network's routing beside the switcher it feeds. Dante Controller has no remote-control
interface, so this is our own Dante routing control — netaudio's reverse-engineered control
protocol, ported — plus interoperability through Dante Controller's **preset files**, written and
read. `docs/DANTE.md` is the design, the protocol table with a source for every row, and the
first-device test. Off by default (`OFF_UNTIL_TESTED`), preview on the settings row, and the grid
opens **locked**, because it reaches every device on the audio network and not only the switcher.
**It holds a UDP socket per Dante device, and `server/awj.js` forbids exactly that — for the
switcher.** That prohibition is about the store mirror. A Dante subscription is held by the
receiving device and nowhere else: not in the store, not in the page, so there is no mirror to
contradict; it changes without us (Dante Controller, a console's Dante page); and ARC is datagrams
with a transaction id, with no client budget like the frame's five AWJ clients. So it is read on a
timer, the Matrix Routing argument. `plugins/dante/link.js` says so at its head.
Five things are load-bearing:
- **No driver writes its own state.** Every write — grid, cue, OSC, snapshot, preset — is a
`plan()` (only what differs), sent, then the receivers **read back**, and `confirm()` reports what
each device says now: `confirmed` / `unconfirmed` / `refused` / `missing`. `confirmed` is the
subscription; whether audio flows is its *status*, reported beside it. A device that answers a
write with success and changes nothing is `unconfirmed`, and the simulator has one to prove it.
- ⚠️ **Never bind UDP 5353.** The OS responder owns it and Dante Controller and DVS depend on it.
Discovery asks from an ephemeral port (RFC 6762 §6.7 legacy unicast), so answers come back to
us alone. Do not "simplify" to SO_REUSEPORT on 5353: it splits the multicast stream between two
readers and breaks the software this sits next to.
- **The codec is a port, and its evidence is labelled.** Each table in `protocol.js` names the
netaudio file and function it came from. `test/fixtures/dante/netaudio-vectors.json` keeps
netaudio's account of every byte vector: Dante Controller's own requests (2.8.9 and 2.7.41
subscription pages, 2.8.12 status queries, 2.8.15 page continuation) are independent evidence;
netaudio's golden command bytes are its own encoder's output and prove agreement only. A
correction belongs upstream first.
- **Three write forms, chosen by the advertised revision** (`writeForm` in `supervisor.js`):
`modern` (2.8.9+, the `0x3410` page Dante Controller sends), `page-2729` (2.7.41, the `0x3010`
page under `0x2729` it sends — with `.` for the receiver's own channels), and `classic`
(netaudio's `0x27FF` add/remove, for 2.8.1 and for a device added by address that read cleanly
the classic way). A revision netaudio has no observation of is read and never written.
- ⚠️ **`tools/dante-sim.mjs` is built from the same tables, so it is not evidence.** Every
end-to-end test, and the browser check, ran against it.
⚠️ **Rules for an agent working on it:** send no control packet to a real Dante device. Set the
plugin's `discoveryTarget` to the simulator (`127.0.0.1:`) before switching it on — with a
target set, discovery asks only there and never the network — and add no real address to
`manualDevices`. Passive mDNS browsing is harmless; reading a device over ARC is not passive.
⚠️ **The switcher's card is read from the store on inference.** `device/system/deviceList/items/
/dante/status/pp/id` is taken to be its Dante name (32 characters in the model, and
`AQL-Simulator` on the simulator), and `DANTE__CHANNEL_` to be Dante channel (b − 1) × 8 + c.
Neither has been put next to a real card. A frame slot with no card reads `UNKNOWN`,
`NOT_INITIALIZED` and no id, and is skipped. `switcher.js` reads the Audio Matrix's paths itself —
a plugin never imports another's folder.
### A Pixelhue console (`plugins/pixelhue/`) — **preview**
A U-series event controller driving the switcher. The whole subsystem turns on
one observation, and everything else follows from it: **a console is not a
keyboard.** It is a peer that already knows what a screen, a layer, a source
and a memory are, and its control service speaks a protocol about those things.
So this publishes a *model* and answers *intents*, and has no key map at all.
```text
data-change → {screens, layers, inputs, presets} the console labels,
lights and pages itself
tag 0x00101307 ← {command: 300, payload:{id: 2}} what the operator meant
```
The identity round-trips: a screen published as `uid: "S1"` comes back as
`uid: "S1"`. That is why there is nothing here to keep in step with a firmware,
and why `vendor/surface/`'s binding engine — right for a MIDI controller — is
the wrong shape for this.
⚠️ **It has never worked against a console.** It was built from the firmware
and proved against a real UCenter running headless in a VM, which is enough to
pin the protocol and not enough to pin the hardware. The first real console, a
user's U5 mini, refused its socket on 2026-10-22 (below). It is off by default,
the settings page says preview in as many words, and `docs/PIXELHUE.md` lists
what is unverified.
Five things are load-bearing:
- ⚠️ **`index` is the key position and it is 1-based.** Publishing from zero
silently drops the first object of every bus — no error, no complaint, a
panel one short. `test/pixelhue.test.js` pins it.
- **It holds a socket to the console and nothing open on the switcher.**
`plugins/pixelhue/ucenter.js` argues the first half (a console is not in the
store; there is no mirror to contradict and no tab to depend on);
`plugins/pixelhue/supervisor.js` argues the second (a burst of `exchange()` gets,
closed, because `awj.js`'s rule does not need beating for this). The price is
no live tally, and it is written down rather than hidden.
- ⚠️ **A recall lands in preview, always**, whatever the panel's PGM EDIT is
doing — the same choice every other recall path here makes. And a source
change is **refused** when the preset letter cannot be read, exactly as
`server/osc.js` refuses `preview`/`program`.
- **The codec is vendored, not written here.** `src/vendor/pixelhue/` is
pixelhue-bridge's `core/`, and its `tags.js` still describes tag
`0x00101307` as business data — it is the *command* report, and the
correction belongs upstream rather than in a vendored file.
- ⚠️ **The socket's path is the model's, and a mini's is not a U5's.** A U5 /
U5 Pro runs UCenter, at `/unico/v1/ucenter/ws`; a U5 mini runs
`nvcontroller`, at `/unico/v1/ws`, and its binary has no `ucenter/ws` at all.
Both used the U5's until 2026-10-22, when a real mini answered it with an
ordinary HTTP 200 — and the stand-in had served the same wrong path, so no
test noticed (the GUID typo in `ws-client.js` again). `CONSOLE_MODELS` holds
`wsPath` and `clientType`; `test/pixelhue.test.js` pins the mini's URL to
the firmware. Client type 5 on a mini is unproven (its own LCD app uses 11),
so an open socket with no key report in 10 s says so on the card.
- ⚠️ **A mini's key grid (TCP 17100) answers `pong\n`, and only a ping that
has a recv() to itself.** Firmware V1.0.3's `liblcdcompanionimpl.so`
(`receiveThread` → `processPingMessage`) hands each recv() of up to 65,534
bytes to the ping check whole, trims spaces and tabs, wants about ten bytes
or fewer starting `ping`, and writes the five bytes `pong\n`. Up to 0.18.9
the stream parser kept the `\n`, took it for the start of the next packet
and lost every pong after the first, so the link declared the console dead
every 15 s (5 s beat, two missed) and redialled 3 s later. The vendored
parser now skips blank bytes between frames (pixelhue-bridge dbd3ad9), and
`grid-link.js` sends a ping only on a socket quiet for `QUIET_MS`, never at
connect, where the first redraw would join it in one recv(). The stand-in
(`test/helpers/fake-mini-lcd.js`) answers the same way, so a test that
draws hard behind a ping fails as a real mini would.
**Console TAKE/CUT: this app as a mini's switcher** (`switcher.js`, `switcher-server.js`; the
setting `pixelhueSwitcher`, u5mini only, off by default, marked preview). A mini sends its own
TAKE and CUT only to the Pixelhue switcher it is bound to, never to a control-service client, so
with this on the app plays that switcher. Proved against the mini's own firmware (V1.0.3) in the
private pixelhue-re rig, never a mini on a desk. The protocol research stays in pixelhue-re; this
repo describes behaviour.
- ⚠️ **The ports are the firmware's, not ours**: discovery on UDP 5600, HTTP and the WebSocket on
TCP 19999, which the LCD app has hard-coded. On a Mac or a Windows PC with PixelFlow installed,
its UCenter service holds 19999 (macOS refuses every other bind on it; winlab's `ucenter_win`
holds `0.0.0.0:19999`), and the card says so in words, not as an errno.
- **Ping the WebSocket at least every 4 s**, with WebSocket ping frames; NOVA keep-alives do not
count. This app pings every second.
- **What a take needs**: `screen/list-thumb` (without it the LCD logs "Can not take"), `tbar` as a
list (an object fails the whole decode), `node/detail` with work mode 0, a non-empty
`node/ethernet`, and an empty `ucenter/device-list` (listing this app there stopped the rig's
takes). The LCD takes only the screens selected on its own SCREEN row.
- **A refused take shows nothing on the console**: the reply is logged and dropped, with no retry.
The history and the card are where a refusal (the lock, nothing selected) is said.
- **Bind keeps before it writes.** The binding and the search list (`ucenter/device-ips`) go to
storage (`pixelhue-switcher`) before anything is written to the console; a second Bind keeps the
first; Unbind forgets them only once both read back. The search list is kept exactly as read:
until the rig run of 2026-11-06 it was kept without this app's own address, and a console that
already searched that address lost it at Unbind.
- **The serial and token are made once and kept**, so a restart never strands a console that is
holding the old token.
- ⚠️ **Never send the search port anything but a whole discovery frame.** On 2026-11-06 the rig
mini's discovery listener panicked on a 19-byte reply (`slice bounds out of range [40:19]`),
stopped searching until it was restarted, and spun writing its log until its 2 GB tmpfs was
full. `discoveryProbe` ignores anything that is not a search, and the switcher sends nothing
else.
- **Only the console is served**: its address, resolved from `pixelhueHost`. Both sockets bind all
addresses, because the search is broadcast.
- ⚠️ **A binding made while the console runs needs a restart.** On the binding change the LCD
app's ScreenKeyBiz and LayerKeyListBiz look the new switcher's serial up in its own
`ucenter/device-list` before the LCD has a token, find nothing and give up, and the SCREEN row
usually stays empty until the LCD app restarts (its start-up path does no lookup).
- **Sometimes it works anyway.** In the VM a live Bind now and then picked the screens up
through the same login loop that brings them in at start-up. That is a race; never count
on it.
- **Re-sending the binding alone did not cure it.**
- **With this app listed in its own `device-list` as well,** it worked once and could not be
repeated, so it is not built. The patch is in pixelhue-re's rig notes, fifth pass.
- Bind says to restart. Don't remove that for a cleverer binding until a mini on a desk shows
the restart is not needed.
- **The LCD app's own read of `screen/list-thumb` is the sign it has picked the screens up.**
nvcontroller reads it too, at every login, so `switcher-server.js` tells them apart by
User-Agent: the LCD app sends none, nvcontroller sends Go's. `last.screens` and the card's
**Console screens** count the LCD app's reads only, and only one after Bind (`boundAt`) counts.
The LCD app logs in again about every 2 s, so a login is no sign of anything.
- ⚠️ **Never hold the 17100 key grid while the console starts.** Held then, `list-detail` is
handled only by InputKeyBiz and CustomKeyBiz and the SCREEN row stays empty. Bound, a grid
close (`#holdGrid`) and Bind let it go until the LCD app has read the screens, plus
`GRID_AFTER_SCREENS_MS`, or `GRID_HOLD_MS` of it talking without, said in the history. Taking it
after the pickup is harmless. Unbind and turning the mode off take it straight back.
- **Bound, no model is published** (`#playing()` in `refresh`, `#republish` and `#watchForWipe`).
The LCD app publishes its own from this app's screens, and the wipe watcher would republish
over it. Its effect apart from the grid's was never isolated: a precaution, kept cheap.
- **Two screens selected stop the LCD app after the first TAKE or CUT** in the rig ("task
submitted to thread pool", never "task executing"); bound to the rig's fake it did no better,
so it is not this app. One screen works every time. Say so; don't paper over it.
### A Barco EC panel (`plugins/barco-ec/`) — **preview**
An EC-30, EC-40 or EC-50 plugged into this machine, driving the switcher with no browser open.
`docs/BARCO-EC.md` is the operator's page and the proven/not-proven list. **It has never met a
panel**: the protocol is qubered/ec50-panel's (MIT; proved on a real EC-50 under Windows), and here
it has met only `test/helpers/fake-ec-panel.js` and a simulator.
**It is the Pixelhue panel's opposite.** A Pixelhue console is a peer that is handed a model; an EC
panel is a CPLD behind an FTDI chip that reports key numbers and shows whatever pixels it is sent.
The Toolset is where its meaning lives, so here `plugins/barco-ec/core.js` is the Toolset: what
every key means, every label, every lamp. Load-bearing:
- **The panel's bytes are `src/core/ec-panel.js`, not the device host's.** The device driver and
the plugin both read the key table, and Docker has no `devices/`, so it lives in `core/` (no I/O)
the way the Speed Editor's lives in `src/vendor/`. The table is Barco's own `showConsoleMap.csv`
(identical in Event Master 9.2.68800 and 10.0.3.3021); `test/barco-ec.test.js` checks it against
any Toolset installed in /Applications. **Never edit it by hand from a photo of a panel.**
- ⚠️ **Nothing written takes effect until latched** (`0x3828`: 1 lamps, 2 framebuffer), **the
framebuffer goes out twice** (double buffered — one pass leaves a torn panel), its 4-byte header
overlays cell 0 and **zeroing it discards the whole write**, and **every read reply is one
transaction late**, so the driver polls one register and throws its first reply away. The
pretend panel enforces all four; a driver change that breaks one fails there.
- **It runs in the server, as the Pixelhue supervisor does**, because a desk panel must work with no
page open. That is the one exception to "a device's controls become switcher writes in the page"
(below): the device host still knows only the panel; the meaning is in this process; the
switcher is read in bursts and nothing is held open on it. The price is the Pixelhue panel's: no
live tally (a reread every 15 s and after each press that changes the switcher).
- **What a press writes is `src/core/console-intents.js`, and how the switcher is read is
`server/console-switcher.js`** — both moved out of the Pixelhue plugin on 2026-10-20 so the two
consoles cannot drift. Pixelhue's console suite was rerun on the 6.2.73 simulator after the move:
31 pass, 3 skip, as before. The move also fixed `labelPath` on a Midra (it read `split()`'s object
as a pair and threw).
- **A console's sources are the ones the Web RCS's source picker offers**, never the first N slots
(`sourcesWanted` in `server/console-switcher.js`). On LivePremier an input is offered when it is
`status/pp/isAvailable` and `isEnabled` and its `preconfig/inputs/current` global is `USED`
(`availableInputAsSourceKeysSelector`, 6.2.73; the rule `NLC.sourceOffered` keeps); stills the same
against `stillList`. Every slot of the namespace is asked (`dialect.inputSlots` / `stillSlots`:
256 and 192 on nlc) and a console's `inputs` / `stills` limit is how many it keeps. Until 2026-11-05
the read stopped at slot 24 and gated on `mapping/pp/isValid`, so a U5 mini on an Aquilon never
saw its later cards; on a Midra it read nlc's keys and found nothing (`INPUT_n` and the plug's
label now, fixture-only).
- **The panel takes one program at a time.** While this holds it the Toolset cannot. Turning the
setting off clears the panel and lets it go. ⚠️ On Windows the panel belongs to FTDI's driver,
installed by the Toolset; D2XX is its API. **Never suggest Zadig/WinUSB** to reach it through
libusb instead — the Toolset would stop seeing the panel.
- **The T-bar reports where the lever is**, not progress through a take; `strokeProgress` counts
from whichever end it rested at, so the second throw is a take back, as on the Toolset. The first
reading after connecting is only where it rests, never a stroke.
### An ATEM Micro Panel (`plugins/atem-micro-panel/`) — **preview**
A Blackmagic ATEM Micro Panel plugged into (or paired with) this machine, driving the switcher the
way it drives an ATEM, with no browser open. `docs/ATEM-MICRO-PANEL.md` is the operator's page and
the proven/not-proven list. **It has never met a panel**: the key table, lamp bits and report ids
are node-blackmagic-controller's (MIT, Julian Waller; what Companion drives real panels with), the
handshake is the Speed Editor's on feature report 5, and here it has met only
`test/helpers/fake-atem-micro-panel.js` and a simulator.
**It is the Barco EC panel's shape on the Speed Editor's wire.** The panel is host-driven — ATEM
Software Control normally reads its keys and lights every key — so this plugin is ATEM Software
Control, with a LivePremier behind it. Load-bearing:
- **The panel's bytes are `src/core/atem-micro-panel.js`**, for the reason the EC panel's are in
`core/`. Its handshake reuses the vendored Speed Editor `authResponse`; only the report id
differs (5, not 6). `test/atem-micro-panel.test.js` holds the key table to
node-blackmagic-controller's own shape: fifty keys, codes 1–50, lamp at 13 + 3 × code. **Never
edit it from a photo of a panel**; a real panel that disagrees goes in NOTES.md first.
- **One driver for the family: `devices/blackmagic-hid.js`.** It was `SpeedEditorDriver`, moved
unchanged but for taking a model (`{vendorId, productId, authenticate, battery}`); the Speed
Editor's module is now a subclass and its hardware-proven tests run untouched. A behaviour
change there changes both panels — the Speed Editor's is the one that has been proven.
- **Runs in the server, on the Barco EC panel's terms** (`plugins/barco-ec/supervisor.js`): the
host knows only the panel, the meaning is in this process, the switcher is read in bursts.
Presses go through `src/core/console-intents.js`. The T-bar's stroke arithmetic moved there from
the EC plugin (`strokeProgress`, `STROKE_END`, re-exported from `plugins/barco-ec/core.js`).
- **Tally is read, every 5 s and after each press** — `ConsoleSwitcher.tallyFor`, a burst of a
dozen `get`s for the active screen's selected layer, using `layerSourcePath` (the write's own
catalogue lookup) and `readSource` (the write's spelling, inverted) from `console-intents.js` so
the read and the write cannot name different things. Still a burst, never a subscription; the
Pixelhue supervisor's argument stands.
- **The program row is tally only unless the operator ticks it, and the tick is never saved**
(`setHotCut`, `POST /hot-cut`): it is forgotten when the panel is switched off and when the app
restarts. An ATEM program row cuts to air; a LivePremier's program buffer is a live wall. Keep it
out of the settings.
- **Key n is source n**, as on an ATEM, not the nth valid source: an unmapped input leaves a gap.
MACRO's memories are by slot for the same reason. M/E keys and layer keys are positional (the
screens in service, the fitted layers), because those numbers mean nothing to an ATEM operator.
- ⚠️ **ATEM Software Control on the same machine acts on every press too.** The panel has to be
opened non-exclusively on macOS, as the Speed Editor does. The card and the doc say to quit it;
nothing here can detect it.
- **Letting go leaves the panel dark, and nothing paints after that starts** — `#letGo` stops
painting before it sends the dark report, because a tally read still in flight used to relight
the panel after it (found by `test/atem-micro-panel.test.js`, 2026-10-20).
### An X-keys panel (`plugins/xkeys/`) — **preview**
A P.I. Engineering X-keys (stick, grid, T-bar, foot pedal, X-blox) plugged into this machine,
driving the switcher with no browser open, each key doing the job the operator gives it on the
card. `docs/XKEYS.md` is the operator's page and the proven/not-proven list. **It has never met a
panel**: the model table and the bytes are SuperFly.tv's xkeys library's (MIT, 3.3.0 at
3016c1bfec96; what Companion drives X-keys with), and here it has met only
`test/helpers/fake-xkeys.js` and a simulator. Load-bearing:
- **The model table is generated, never typed**: `src/core/xkeys-products.js` comes from the
library's `products.ts` by `scripts/gen-xkeys-products.mjs `, which drops the
interface boards. A new panel is a re-run, not an edit.
- **The bytes are `src/core/xkeys.js`**, no I/O, read by the device host and the plugin alike.
`test/xkeys.test.js` replays the library's own recordings of real panels
(`test/fixtures/xkeys-recordings.json`): every described key, T-bar, jog and shuttle event
decoded to what the library recorded, and every recorded backlight command matched byte for
byte. Change a decoder or a builder and that replay says whether it still agrees. **Never edit
either from a photo of a panel**; a real panel that disagrees goes in NOTES.md first.
- **A key's job is the operator's**, kept per model in `xkeysLayouts`, normalised in `core.js`
(key ids are indexes, `n` 1–999, screens `S`/`A` and a number). A model with nothing saved runs
`suggestedLayout`; a saved `{}` is a saved, blank layout and the suggestion must not come back.
- **Every source and recall lands in preview.** There is no hot-cut job, on purpose: a blank key
is too easy to hit. Keep it that way unless it's asked for, and then make it the ATEM program
row's unsaved tick, not a job.
- **Runs in the server on the ATEM panel's terms**: the supervisor is that one's shape, presses go
through `src/core/console-intents.js`, the switcher is read in bursts by `ConsoleSwitcher`.
`destinationsOf`, `activeOf`, `layersOf`, `sourceAt`, `memoryAt` and `selectOnly` moved from the
ATEM plugin into `console-intents.js` for it (2026-11-05); `plugins/atem-micro-panel/core.js`
re-exports them, because a plugin never imports another plugin's folder.
- **Opened shared (`nonExclusive`)**, as the ATEM panel is, so Companion or MacroWorks on the same
machine hear every press too. The card and the doc say to turn the panel off there; nothing here
can detect it. Only the first X-keys by path is driven; the card says how many more there are.
- **A panel that never answers Generate Data is taken as ready after three asks**, its keys read
as they change: some firmware may not answer, and a dead card would be worse than a missing
first state.
- **Testing through the kernel without a panel, on Linux:** `test/helpers/uhid-xkeys.py` makes a
virtual XKE-124 T-bar with uhid (root; on Ubuntu the module is in
`linux-modules-extra-$(uname -r)`), and `test/sim/xkeys-uhid.sim.test.js` drives it through the
real forked device host and node-hid on hidraw: the only X-keys test where the bytes cross a
kernel. hidapi reports a uhid device's interface as -1, which `findProduct` accepts for that
reason. The panel can be unplugged and replugged from its control FIFO. The same trick would
serve the other HID panels; nobody has written their uhid twins yet.
### Lighting desk control (`plugins/desk-control/`) — **preview**
A lighting desk sending Art-Net or sACN drives the switcher the way it drives a media server:
Master, Screen and Layer fixtures, GDTF files to import, no browser open. `docs/DESK-CONTROL.md` is
the operator's page and the run/not-run table. **It has never met a real switcher**: MagicQ PC
1.9.6.5 on the same Mac and a pretend desk sending real Art-Net at 40 fps, against the 6.2.73
simulator. The patch also comes as an MVR, and the switcher can be a CITP media server. Load-bearing:
- **The channels are defined once, in `src/core/dmx-personality.js`**, and the engine, the patch,
the CSV and the GDTF files (`src/core/desk-gdtf.js`) all read that. Never hand-edit a `.gdtf`.
Moving a channel changes every show file that patched the old one: bump `GDTF_VERSION`
(`plugins/desk-control/server.js`) so a desk's library keeps both. The files validate against
the official GDTF 1.2 `gdtf.xsd` (`xmllint --schema`); keep it that way, and keep names free of
dots (GDTF node links are dot-separated).
- **Nothing fires on a first frame.** After a start, a restart of the desk, a backup desk taking
over or a repatch, a fixture's first frame is only a baseline; `DeskEngine.update` with
`fresh`, and `DeskEngine.forget`. A desk sitting at Take = full when the app restarts must not
take. Triggers fire on a *rising* 50% crossing; memories on a change to non-zero.
- **A screen ignores the desk until its Control channel rises**, and a lost desk does not let go
of a screen (`forget` keeps the control modes; nothing is written meanwhile).
- **Recalls go to preview**, as everywhere in this app, through `console-intents.js`'s
`writesFor`, so a desk's take and a panel's take are one function.
- **One source in control per universe, never a merge** (`src/core/dmx-input.js`): HTP of two
layer sources means nothing. Highest sACN priority, Art-Net as 100, ties to the lowest key,
sACN preview data ignored. This app's own sACN (source name `LivePremier Plus`, the Triggers
plugin's) is ignored outright; its Art-Net is not distinguishable — don't point a Triggers
Art-Net destination at a universe desk control listens to.
- **The modes only add.** Cue, Compact, Standard and Full are each the one before with channels
on the end; Master and Screen are the same in all four. **Size 0 is the memory's look**:
`layerLook` returns nothing past source, opacity and colour while W or H is 0, and the engine
only writes a part whose value changed (`sameValue`). Keep both, or a desk patched in a bigger
mode and sitting at zero overwrites every memory's geometry. What a part becomes on the wire is
`lookParams` → `layerSpec` → `fitValue` (`core.js`): a value the platform's catalogue refuses
is dropped, not sent, and a part the platform lacks (a Midra's key) is passed over.
- **A position needs the screen's size**, read with the preset letters before every burst
(`dialect.canvasSize`), never cached: a preconfig can change it. No size, no position written,
a quiet note. X and Y are from the centre; NLC needs the anchor written `MIDDLE_CENTER` with them.
- **Switcher to desk (`feedback.js`, the watcher in `supervisor.js`)**: `TakeWatch` decides, the
supervisor polls (`WATCH_MS`) on the held link and fires through the Triggers plugin's
`triggers` service (`ctx.use`, null when that plugin is off — say so, don't fail silently). A
take fires once: at `EFFECT_FROM_…` when seen, else at landing; the first reading is a baseline.
**The echo guard is `#ownTakes`**: every take or cut desk control writes is recorded before it
goes, and the next take seen on that screen is the desk's own and fires nothing. Any new path
that writes a take for the desk must go through `#taken`, or the "VT state" cue that takes the
switcher loops. It watches with desk listening off, so `#shut` keeps the link while watching.
- **The supervisor keeps order per screen** (`supervisor.js` argues it): a queue per destination,
one step per burst, `minGapMs` between bursts; layer values coalesce only within a run, never
across a recall, take or cut; `settleMs` after each of those; the preset letters read before
every burst of layer values, held mid-transition; a recall, take or cut older than `STALE_MS`
dropped, not sent. The desk's layer values are written again after anything replaces the buffer
it edits (`DeskEngine.layersFor`).
- **A take has not happened until it has landed.** The simulator reports the resting state a take
left for the whole take (measured 2026-10-30: a 1.0 s take read `AT_DOWN` throughout and `AT_UP`
at +1.02 s, nothing in between), so "settled" read 150 ms after a take is the old letters, and
the re-push went to the letter going to air. After a take or cut the supervisor holds that
screen's layer values until the transition reads differently from before it, or the take time
plus `landMarginMs` has passed. MagicQ found this; the unit and simulator tests now fail without it.
- **It holds one AWJ connection** — `server/awj-link.js`, the one exception to `awj.js`'s rule,
argued at its head (AWJ pushes nothing, measured 2026-10-30, so a held socket cannot become a
mirror). `ConsoleSwitcher` takes an `exchange`, so the same reads run on either. Idle close at
5 s. Do not hand the link to anything that would subscribe or write into the mirror.
- **The sockets bind `0.0.0.0` whatever the app is bound to**: Art-Net arrives by broadcast,
which a socket bound to one address never sees. The allow list is the lock. `deskInterface`
only chooses what ArtPollReply says and where multicast is joined.
- ⚠️ **A desk on the same machine shares UDP 6454**, and macOS 26.4 hands a unicast datagram to
one of the sockets only: **the one that bound the port first** (measured 2026-10-30 — the app's
when it started first; MagicQ's own when the app started after it, and a socket bound later
still heard nothing). So an ArtPollReply to one of this machine's addresses goes by broadcast on
that interface, and a desk unicasting to 127.0.0.1 reaches the app only if the app was there
first. MagicQ reopens its socket when its network IP address changes.
- **Testing:** `test/desk-control.test.js` stands the supervisor up on port 0 on loopback with
`pollReplyPort: null` and injected interfaces; `fakeAwj` copies its initial store, so change
the pretend switcher through `awj.store`. `test/sim/desk-control.sim.test.js` uses the real
ports, sends a desk's 40 fps itself (a desk refreshes; a test that sends only changes lets
Art-Net time out after 10 s and the next frame is a baseline), and polls on the simulator's own
subnet — a Mac with a VM adapter lists that first. `guardScreen` puts back only the layers in
use (`fittedLayers`), so a test that writes an empty layer leaves it changed on the shared rack.
⚠️ A scratch script using the harness needs `LPP_SIM` too: without it there was no AWJ host and
Node connected to localhost:10606, which on this Mac was another session's tunnel to a switcher
on the tailnet. `awjGetAll`/`awjReplace` now throw instead; keep it that way.
- **The link is pointed before it is used** (`#pointAt`, from `refresh` and `#ensureDialect`
both): which switcher the held connection is to is recorded before the first read, not after it.
Recorded after, a desk connecting over CITP during that read looked like a re-point, closed the
link and failed the read (the simulator test failed four runs in five, 2026-10-30).
- **The patch as MVR (`src/core/desk-mvr.js`)**: fixture IDs come from the switcher (Master 1,
S*n* n×100 + layer, A*n* 5000 + n×100) and UUIDs from the host and the fixture's id, never at
random, so importing again updates the desk's patch instead of doubling it. Keep both stable.
- **CITP (`citp.js`, `media.js`, `pictures.js`; the bytes in `src/core/citp.js`) only reports**:
nothing a desk sends over it writes to the switcher. Library DMX is the Folder value and element
e is File value e + 1, so reordering `FOLDERS` is a channel change as far as a desk is concerned.
Layers are read once a second only while a desk is connected. "Only these desks" is checked on
accept. ⚠️ **MagicQ 1.9.6.5 doesn't discover**: it connects straight to TCP 4811 at the IP typed
in, speaks MSEX 1.0, sends no PNam or CInf, and has no socket on UDP 4809 (measured
2026-10-30). So keep 4811 the first choice, answer a session in the version its requests come
in (`seen`), and send `StFr` down the TCP connection to a session before 1.1 (the spec forbids
that only from 1.1); multicast from 1.1. Multicast goes out of a socket per interface: one
socket sends on one, and a Mac can list a VM adapter first.
- **The image helpers are `server/image/`** (PNG decode and encode, JPEG encode, resize), shared by
`snapshot-relay` and `desk-control`. A plugin never imports another plugin's folder.
- **Testing CITP:** `test/desk-citp.test.js` stands the server up on port 0 with `targets` so its
multicast arrives on loopback, and a pretend desk on TCP. `test/sim/desk-citp.sim.test.js` is
read-only. The 6.2.73 simulator serves no snapshots (404 for inputs and images), so every
picture it gives is a card; to see a real picture in a desk, run a peer with a test pattern
(`picture()` of any RGBA image) instead.
- **Testing with MagicQ PC on this Mac:** back up `~/Documents/MagicQ/show/{lastshow.shw,
status.dat,laststatus.dat,heads/headindex.csv}` first; the GDTF import adds three `.hed` files,
index lines and `~/Library/Application Support/MagicQ/recent_saved_heads.txt`. Network IP a real
interface, Art-Net type *V4 Unicast only*, universe 1 unicast to 127.0.0.1, the app started
before MagicQ opens its socket. Its soft keys ignore AXPress (a one-pixel drag presses them), and
it ignores SIGTERM; its quit confirmation can open on another Space, and is a window of its own
(`CONFIRM`) that a click on the main window doesn't reach. A multi-mode GDTF asks for the mode on
import. In the programmer's advanced view, click a cell, type, Return; select only the head you
mean, as the columns are shared between head types. Check **Rec Options** before recording: a
latched *Rec Remove* makes REC + S remove instead. In demo mode its OSC, MIDI and remote inputs
are locked, so it can't receive the switcher's triggers. For CITP also back up
`~/Documents/MagicQ/thumbs/`; the media server line is **Setup → View System → Media** (Return
steps the Type list; *CITP MSEX* is the sixth), and a head's **Media → Server Type** takes a
number (5 is CITP MSEX). Import an MVR only into an empty show (**NEW SHOW**): over a clashing
patch it imported nothing and the second attempt hung MagicQ until SIGKILL.
**NDI** needs MagicQ 1.9.8 or later (the 1.9.6.5 in `/Applications` has none; 1.9.8.3 ran from a
folder of its own beside it). Type *NDI* is sixteen Returns on from None; double-click the IP address cell to pick the
sender. In demo mode it lists the senders and shows **Locked**, and never connects, so it cannot
test NDI. Its *Simple generic console* start opens the Simple layout, which has no SETUP key:
press **Full**, top right. Its windows can't be brought onto a full-screen Space, so ask for a
desktop Space before driving it.
### grandMA3 (`plugins/grandma3/`) — **preview**
A grandMA3 desk, or onPC with a wing, driving the switcher through the OSC playback feedback the
desk sends by itself (an OSC line with Send on, Prefix `ma3`). `docs/GRANDMA3.md` is the
operator's page and the proven/not-proven list. **It has met grandMA3 onPC 2.4.2.2 on a Mac, no
wing**, both as recorded bytes (`test/fixtures/grandma3-2.4.2.2-feedback.json`) and live through
the app to the simulator. Load-bearing:
- **It is an `oscAddress` subtree, `/ma3/`, with no socket of its own.** OSC input must be on.
A line's target is sent through `server/osc.js`'s `createOscDispatcher`, the function a UDP
packet goes through, so it meets the same refusals (`preview`/`program`, releases, `$`
variables) with the same words. Never give it a second copy of those rules. Its dispatcher is
handed every subtree but its own, and `parseMap` refuses `/ma3/` targets, so a desk cannot feed
itself.
- **The desk's own USB wing is out of scope, on purpose.** It unlocks onPC's parameters; its
protocol is unpublished, and impersonating it would be defeating a licence. Listen to the desk.
- **Type tags matter here.** A fader's position is `,sif` and a knob's nudge is `,sii`, with the
same shape otherwise, so `decode` returns `types` on every message and `handle` gets
`{ types }` as a third argument from UDP. The Console path has no tags; a typed number is then
read as a fader position.
- **The object address is not a constant.** 2.4.2.2 sends Sequence 1 as `14.14.1.6.1` where MA's
2.4 manual says `13.13.1.6.1`. Nothing in the code knows what `14.14.1.6` means: lines name what
was heard, and the card lists the unmapped ones. Never hard-code a sequence's address.
- **A fader is one of three things by its target** (`core.js` `actionFor`): `/norm` with no value
follows the fader, one write in flight and the newest waiting (an older reading must never land
last); `tbar` is the consoles' stroke (`tbarWrites`, `strokeProgress`, first reading only where
it rests); anything else is a button with hysteresis (fires up past 50 %, re-arms below 5 %,
never armed at first sight). Keys fire on press only.
- **A changed line resets only its own handle.** Saving the map mid-show must not drop another
fader's stroke or arming (`Grandma3Bridge.apply`, tested).
- **onPC can be driven headless for testing**:
`/Applications/grandMA3.app/Contents/MacOS/gma3_2.4.2/app_terminal HOSTTYPE=onPC`, fed
`cmdline 127.0.0.1` then command lines (`Go+ Page 1.201`, `FaderMaster Page 1.201 At 40`,
`Lua "…"` with single quotes inside). It does not exit at end of input: put a timer on it. The
OSC line can be set from Lua on `ShowData().OSCBase`; set `PreferredIP` to `127.0.0.1` on a Mac
with Parallels, or its default `10.0.0.0/8` sends to the VM bridge and nothing arrives.
### Desk (`plugins/desk/`) — **preview**
The software for the LivePremier Plus desk (`stoatworks-labs/lpp-control-surface`, prototype one,
not built): a Mynah keypad typing into a Console line, four encoders and three paged wheels
through awj-surface's engine with `lpp-surface-p1`, and a 1920 × 550 strip screen.
`docs/DESK.md` is the operator's page and the run/not-run table. **It has only met a CoreMIDI
virtual source** on the same Mac, in Chromium, against the 6.2.73 rack simulator. Load-bearing:
- **The key table is the hardware repo's, not ours.** `KEYS` in `keypad.js` follows the keymap
block of that repo's `docs/KEYPAD.md`, which `mechanical/layout.py` writes; the knob pixels in
`core.js` come from the same file. `test/desk.test.js` reads it when a checkout is at
`~/hardware/video/lpp-control-surface` (or `LPP_DESK_KEYPAD`) and skips otherwise. Move a key
there and change it here; never the other way round.
- **A big key's other switches are swallowed** (`SECOND_SWITCHES`). If a firmware sends all four
of TAKE's notes and more than one gets through, the take is followed by the take back.
- **TAKE is `runCommand('Take')`, not a word.** It goes the way a typed line does (Preview lock,
the log) and leaves the line alone. Shift+TAKE types it.
- **Nothing types Program but the Program key**, and the line under the command line says whether
Enter reaches program (`reachesProgram` in `plugins/console/panel.js`). Say "can't tell" for raw
languages; never "no".
- **The sticky scope is the desk's line only.** The `console` service's `line()` passes
`stickyScope: true`; the typed Console tab and pop-out keep none, as before. Don't change that
default: a Select typed weeks ago silently scoping a Take is the failure.
- **The desk lives in the Web RCS tab; the screen only draws.** `screen.js` reads
`own.snapshot()` and calls back into the desk, so closing the screen never stops TAKE. It
doesn't borrow the vendor's stylesheet and it scales, never reflows: a cell has to stay over
its knob.
- **One desk per browser** (Web Lock `lpp-desk`). MIDI Mapping takes no lock, so the profile isn't
on its list: both on one port would double every write.
- **Wheel pages are awj-surface's `page` modifier** (`profile.pages`, `binding.page`,
`engine.showPage`), vendored from upstream a129def. Change it upstream and sync; never edit
`src/vendor/surface/` here.
- **Testing in Playwright:** Chromium 149 refuses `requestMIDIAccess`, even without sysex, unless
both `midi` and `midi-sysex` are granted. The page's writes are best witnessed from
`page.on('websocket')` frames plus the harness `Link`, with `guardScreen` around everything.
### The Background Slicer (`plugins/bg-slicer/`) — **preview**
One picture cut into a background per output, put into the image library, the
stills and a background set; or each output fed from an input, with the media
server's output map exported. `docs/BACKGROUNDS.md` is the design and the
proven/assumed table; `core.js`'s head is the cut, and `src/core/backgrounds.js`'s the model
of an output it cuts against (shared with Resolume Mapping since 2026-10-20; `core.js` still
re-exports every name it moved). Off by default — it
writes to the library, stills, still capacities and background sets, and has
only met a simulator.
Load-bearing, each read off the 6.2.73 bundle and proved on the simulator:
- **A background is 1:1 in the output's raster**, so an image is exactly
`canvas/status/pp/{maxWidth,maxHeight}` and a still is set `rescale`
`NO_RESCALE` — "Downscale to capacity" would resample a cut made to be exact.
- ⚠️ **An output's slices are its connectors, not areas of the canvas.**
`slices/sliceList/items//pp.left/top` is connector k's place in the
output's (group's) raster and `aoi/pp` its size; on the screen canvas it sits
at `canvas/status/pp.left/top + (slice − boundingBox) × pitch`. The first
reading of this field — canvas position plus area of the raster — gives the
same answer for the one full slice a simulator has, and the wrong one for
every group.
- ⚠️ **A set's content write is not one write.** The Web RCS's
`axSetBackgroundSetOutputSource` first hands the replaced input or still's
claim (`preconfig/backgrounds/inputList|stillList//control/pp/
useOnOutput`) to the next output still using it (or NONE), then claims the
output for the new one, then writes `content`. `contentWrites` is that
sequence; Undo goes back through it too. Writes under `preconfig/backgrounds`
are immediate — there is no apply step, so a set on program changes on air
and is refused unless the operator says otherwise. The set's label is
`…/backgroundSetList/items//pp/label`, on `pp` itself, 16 characters.
- **Still capacity is a shared budget, and the switcher decides it.** Staged in
`preconfig/stills/new` (helper format, `xCheck` pulse), read back from
`new/…/status`, applied with `xApply` only when nothing that holds something
goes `DISABLE`; otherwise `xCopyFromCurrent` discards it. Never started over
someone else's staged change (`new/status/pp/hasChanged`). Seen on the
simulator: still 45 at 4K took still 46 (`DISABLE`), and back again. After
`xApply` the switcher reports `current` a moment before it clears
`hasChanged`, so `applyCapacities` waits for both — a capacity Undo started
straight after an apply was refused as "changes staged" before it did.
The routine is `stageCapacities` / `applyCapacities` in `core/stills.js`
now, shared with Image Library tools' capacity dropdown.
- ⚠️ **The page mirror is not the switcher's echo.** `page-socket.js` applies
this page's outbound writes to the store, so a refused write reads back as
landed within a millisecond. Every apply and Undo write waits for the
inbound frame with its path and value (`sendAndEcho` in `core/wire.js`, with
`inbound: true`) — on both platforms. LivePremier Simulator 6.2.73: every write the apply sends echoed
exact in value and type in 0.3–20 ms (pulses: both edges, each twice); a
refused enum never. The only store waits left are statuses the page never
writes (library `isValid`, `preconfig/stills/new/status`, `current`).
- ⚠️ **A write of the value the switcher already holds is never echoed** — so
waiting for it fails a write that landed. `changedPaths` (`core/wire.js`) skips the wait
for any path the write list does not change (walked from the mirror, so a
pulse from `true` still counts). It bites on LivePremier constantly: every
simulator still holds `source` 1, and the first free library slot is 1. The
Midra lists drop such writes up front (`withBefore`). Not covered: a path
whose mirror holds a write this page sent and the switcher refused — an
Undo of it waits 6 s for an echo that never comes and reports it.
- **The upload is HTTP, single-flight** (`uploadImage` in `core/stills.js`,
shared with the UMD Generator). `POST /api/device/images/upload`
(`FILES`, `librarySlot` 1-based) answers 503 while another runs; `FINISH` in
the body is the only success, and the library's `isValid` echo is the proof.
- **A picture is decoded with `colorSpaceConversion: 'none'`.** Without it an
embedded ICC profile changes every pixel on the way in and a "copy" is not one.
- ⚠️ **Rotation is the one guess.** A rotated output's image is turned the way
the switcher turns its layers; whether it turns a background as well is not
known. The panel marks it; `docs/BACKGROUNDS.md` has the check.
- **The simulator's screens have no NATIVE layer** (`capability` OFF), so a set
can be built there and not loaded; the preview load is skipped, not forced.
- **Live EDIDs are the switcher's own**: `edid/cmd/fromTemplate/` (or
`fromCustom/`) pulsed on the input plug — the vendor's "load from
template". Nothing here builds an EDID for this, and Undo cannot take one back.
- **The Arena writer is output-map's**, bundled by `tools/sync-output-map.mjs`
with output-map's own rolldown. Fix it there.
**On a Midra 4K or Alta 4K it is a different model**, `mng.js` + `apply-mng.js`,
picked by `model.js` off the dialect; the panel draws whichever `plan.platform`
says, and the picture, placement, cut, render and exports are shared. Read off
the Midra 4K simulator 3.2.29's client and server bundle (Alta 4K 1.3.7's
matches) and proved on that simulator:
- **One picture per screen.** The image is the screen canvas, into one of the
screen's four Background Images (`screenList/items//backFrameList`) at
`mode` `1_1`, and an Auto Crop set (`backgroundSetList/…/singleContent` =
`PRESET_FRAME_`) has the switcher crop it per output. The frame's
`status/pp/{width,height}` is the size it is shown at — the write waits for
the canvas size there. Custom (`MULTI_CUSTOM`) is the live mode: an input per
output. A preset loads a set through `presetList/items//background/
source/pp/set`. `backgroundLayerType` in the applied preconfig decides what a
screen may show.
- ⚠️ **The upload takes no slot.** The server imports with
`AUTO_SLOT_WITH_DOWNSCALE`: the first slot with `isValid` false, even one a
frame points at — which then shows the upload. The plan refuses when a frame
points at the predicted slot; the write re-checks before each upload. The
shared simulator's S1 BKG1 points at empty slot 1, so it refuses there, by
design.
- The page mirror is not the echo here either (above): the Midra simulator
echoes an accepted write in ~1 ms and a refused one never.
- No still capacity, no claims, no set label, no rotation, slices or groups on
this platform — the panel shows none of them there.
**A document — a PDF, or a PowerPoint, Keynote or OpenDocument deck — is a
picture with no pixels** (`deck.js` pure, `document.js` page, `convert.js` + `server.js`
the server half; `docs/BACKGROUNDS.md` "Documents"). Run on the 6.2.73
simulator through the browser, every write read back over AWJ (2026-10-20):
- **A page is drawn at the size it is used, never scaled to it.** pdf.js
(`src/vendor/pdfjs/`, MANIFEST-checked by `test/bg-slicer-deck.test.js`)
paints each page into a canvas of its placement's whole-pixel size, and the
cut of that is 1:1 — so a document's plan must give `buildPlan` the
placement's own size as `image` (`placementUnits`), not the page's nominal
96 dpi one, or every cut becomes a resample. (Nominal is 72 dpi for a `.key`,
`pageDpi`: Keynote's pixel is a PDF point.)
- **A deck's plan is the slicer's plan with a screen entry per page**, each
page planned knowing what the pages before it took (`opts.reserve` in both
`buildPlan`s). The apply, the journal and Undo are the slicer's; do not
write a second apply for pages. `entry` keys the images, `setLabel` /
`stillLabel` name them, `preview: false` keeps all but page 1 out of preview,
and an output with no still (or no frame) is a library upload alone.
- ⚠️ **PowerPoint, then Keynote, then LibreOffice** (`ENGINES`). PowerPoint
over AppleScript, the deck copied into its sandbox container under a unique
name and found by that name — never `active presentation`, which is whatever
the operator last clicked (one of Allan's decks was open throughout).
LibreOffice is wired (presentation-converter's arguments) and has never run.
- ⚠️ **Keynote is driven by bundle id, Creator Studio first** (`KEYNOTE_IDS`,
found through `NSWorkspace`, no Apple event). Keynote 14.x
(`com.apple.iWork.Keynote`) installed beside Creator Studio launches to a
"Use the New Version" modal and answers nothing, so never launch it while
`com.apple.Keynote` is installed, and never address Keynote by name. This
file once said Keynote couldn't be scripted (-1700/-1728, 2026-10-20 morning);
that was the script: **make `POSIX file` references before the `tell`**, or
the sandboxed app is handed a path it may not read and `open` answers missing
value. Documents are told apart by **id** (never `front document`); close
only a new id, quit only if Keynote wasn't running and nothing is left open;
give the first question a minute so a dialog is reported, not waited on; open
nothing while `playing`. `keynoteRefusal` keeps out files that would leave a
dialog on the operator's screen (password `.iwpv2`, not-a-zip). Proved on
Creator Studio 15.3.1 cold and warm; 14.x alone never run.
- ⚠️ **Hidden slides are not pages.** PowerPoint's PDF leaves them out, so
the server reads `show="0"` from the package and sends `x-lpp-slides`; names
go by slide number only when those account for every page. Keynote leaves
skipped slides out too and its script reports them itself (`{ pdf, slides }`
from `convert`), which wins over the package's: it describes Keynote's PDF.
- **The convert route takes `application/octet-stream` only**, which needs a
CORS preflight this server never answers: no other site can make this
machine open a file in PowerPoint or Keynote. Not an Origin check — behind `tailscale
serve` the Host differs from what the browser used.
- **The launcher must be allowed Apple events** (`NSAppleEventsUsageDescription`,
`com.apple.security.automation.apple-events`). An unsigned local build asked
for Automation and converted (2026-10-20); an unsigned build has no hardened
runtime, so the entitlement itself is still unproven in a signed release.
- **The copy in PowerPoint's container is another app's data**: macOS asks for
App Data before Automation, and a refusal is EPERM on the copy or the
read-back. `containerWords` says so; keep any new file access there behind it.
- ⚠️ **Never `GET /api/device/images/download/` for an empty slot on a
Midra simulator.** Its export never finishes and the route answers 503 until
the web server restarts (uploads carry on). Read a slot back only while it
holds a file.
The Midra library half — `readLibrary`, `nextSlots`, `framesOn`,
`libraryDeleteWrites`, `uploadToNextSlot`, the upload URL — moved to
`core/library-mng.js` on 2026-11-11, because Timer Image uploads the same way;
`mng.js` and `apply-mng.js` re-export what they always exported.
### Timer Image (`plugins/timer-image/`, `core/library-mng.js`) — **preview**, Midra/Alta only
A Midra 4K or Alta 4K (a Pulse 4K) shows its three timers on the multiviewer
and nowhere else: no screen source carries one. This draws the time as a PNG
and keeps one of a screen's four **Foreground Images** showing it; the
operator puts that Foreground Image on air the way a logo goes — the preset's
top layer, then a take — and "Show on preview" does the first half. Offered
where `foregroundImages` holds (the mng `topFrameList` probe), so not on a
LivePremier, whose stills already have a Timer mode (`STILL_SLOT_MODE`
NONE | IMAGE | TIMER). `core.js` pure, `render.js` canvas, `apply.js` the
writes, `stagetimer.js` + `server.js` the server half, `panel.js` the page.
- ⚠️ **A Midra timer publishes its state, never its value.** The tracker
(`createTracker`) keeps the time from the Start/Pause/Stop pulses and states
the page *sees come back* (`frame` events `dir: 'in'`), whoever sent them.
A timer already RUNNING or PAUSED when a page first sees it is `unknown`
until it is stopped or started — said on the panel, never guessed. The
Midra simulator echoes each pulse's edges twice and never changes `state`.
**A real Pulse 4K (3.3.10, 2026-11-11, watched passively while the
operator pressed the buttons in the vendor's page)** sends the pulse's
echo and then the state 2–9 ms later: Pause → `xPause` true ×2, `PAUSED`;
Start → `xStart` false, true, false, true, `RUNNING`; Stop → `xStop` true
×2, `IDLE`. The `x…` flags stay latched true afterwards (the store showed
`xStart: true` on a running timer), so a later press of the same button
shows no rising edge; that is why the tracker takes the `state` messages
as well as the pulses, and every transition is idempotent. While a
countdown runs nothing is sent at all — not a frame in 20 s — and the
timer's status has no field but `state` in 3.3.10's own attribute table.
The page saw `RUNNING` at load, stayed `unknown` through a pause and
resume, went idle at Stop and timed the next Start: replaying the logged
frames through `createTracker` gave the right reading. At zero the Pulse
sends `ELAPSED` by itself, and it came 600.103 s after the rising
`xStart` of a 10-minute countdown: its clock and ours agree to a tenth
of a second over ten minutes.
Start while paused resumes: still an assumption, the vendor has one Start
button and the state reads `RUNNING` either way.
- **Two slots, ping-pong, never an empty frame.** The upload lands in the
lowest empty slot (`AUTO_SLOT_WITH_DOWNSCALE`, above), so `planPush`
predicts it and refuses when another frame points there, the library is
full, or the frame shows a picture that is not ours. Then: upload, repoint
the frame (`sendAndEcho`, inbound echo), and only then empty the old slot.
A failed repoint empties the new upload instead. Ours are named
`lpp-timer-S-FRG-a|b.png` (`ownName`/`ownedBy`); Remove points the
frame at NONE and empties only those.
- **The loop runs on the server's tick, never a page timer.** `GET /stream`
is an SSE stream per page; each whole second (+15 ms) every page gets
`{ now, runner, running, report, stagetimer }`. The oldest open stream is
the **runner** and the only page that pushes; `running` is server memory
only (a restart never resumes on air by itself), and `POST /report` is
refused (409) from anyone but the runner. A hidden tab still gets SSE, so
the picture keeps moving behind another app. A push that outlasts a tick is
not queued: the next push draws whatever second it is when the last one is
done (`pending`). Three failures in a row stop it.
- **Stagetimer** (`stagetimer.js`): Socket.IO v4 over our own `WsClient`
(`secure: true` → `tls.connect` with SNI) at
`/v1/socket.io/?EIO=4&transport=websocket`, `40{room_id, api_key}` to join,
`44{message}` a refusal that stops the retries; polling `get_status` every
5 s while the socket is down. Remaining = finish − server-now (running) or
finish − pause; the server-clock offset is bounded by the HTTP `Date`. The
room and key live in `timer-image-stagetimer` storage (not per device) and
**the key never leaves the server**: no GET returns it, `describe()` omits
it, and an empty key on PUT keeps the stored one. `LPP_STAGETIMER_BASE`
points it at `test/helpers/fake-stagetimer.js` in tests.
**Met a real room on 2026-11-11** (a test room, through the app against
the Midra simulator): the feed joined first time, and `room`,
`playback_status`, `current_timer` and `next_timer` (null with nothing
next) came with exactly the documented fields, no more. A countdown
through its yellow and red, a pause and resume, a +1m, a switch to a
count-up timer and the time over all read as the room's own display did;
the `server_time` offset came out at 1–32 ms.
⚠️ **A room's display settings are not in the API.** Room Settings ▸
Time Formatting (time of day, countdown format) and ▸ Overtime (keep
counting, stop or hide at 0:00; a + or − prefix) never reach the feed, so
the picture is always the defaults: h:mm:ss, and the time over floored
after a `+`. The bdstage port drew a minus there; the real room drew a
plus, which is the default.
Proved on the Midra 4K simulator 3.2.29 through the app (2026-11-11), the
live Pulse never touched: a 5-minute countdown on TIMER_1 pushed every second
for minutes, median 18–25 ms a push (upload ~13–18, repoint ~1–2, empty ~4–5),
one slot held in steady state, the downloaded PNG reading the time; Pause and
resume tracked; Show on preview wrote `UP` top `frame: '4'` at the corner and
left `DOWN` alone; Remove left FRG4 NONE and the library empty.
**On a real Pulse 4K (3.3.10), 2026-11-11, during a live event** —
`tools/timer-image-bench.mjs`, not the plugin's page: the same three writes
(upload, repoint, empty) from a script with show-safe gates, on S2 FRG4
(nothing on either S2 buffer's top layer), slots 3 and 4, with the
operator's go-ahead for S2 and slots 3+ and never program. 69 pushes, none
failed, library and frames left exactly as found:
| | median | 90% | max |
|---|---|---|---|
| upload, POST to `FINISH` | 66 ms | 144 ms | 163 ms |
| slot `isValid` seen on the WS (from POST) | 55 ms | 128 ms | 160 ms |
| frame repoint echoed | 3 ms | 6 ms | 10 ms |
| frame's own thumbnail shows the new time (from repoint) | 19 ms | 34 ms | 37 ms |
| whole push, upload to old slot emptied | 140 ms | 167 ms | 179 ms |
Upload to picture-in-frame is ~70–140 ms, so a push a second has seven
times headroom: 61 seconds of the once-a-second loop never fell behind. The
uploads are bimodal (~55 ms or ~130 ms, about a third slow), as is the
delete echo (~12 ms or ~65 ms). The thumbnail
(`/api/device/snapshots/screens//top/`, 256 px wide at the picture's
aspect) read back the exact time pushed, so it is a usable proof that a
frame holds a picture — not that an output shows it. ⚠️ **An emptied slot
keeps its last file's `fileName`, `width`, `height`, `fileSize` and
`hashName`** with `isValid` false: read `isValid`, never a name, to tell a
free slot (`readLibrary` does). **A Foreground Image keeps a PNG's
transparency** (Allan, from the show, 2026-11-11), so a transparent box
works. Timers on that unit: see the tracker bullet above.
The multiviewer is the only place a Pulse draws a running timer: a widget
whose `source` is `TIMER_1..3` (offered in `multiviewer/status/pp/
sourceValidity`). `/api/device/snapshots/multiviewer/1` is a real 512 × 288
picture of the multiviewer output on hardware (not a placeholder, as on the
simulator), so reading digits off it is a possible second source for a
timer that started before any page saw it — untried, and on that show no
widget carried a timer.
Still unproven: what an output shows (no camera on it, and it never went on
air), flash wear over a long show, and the plugin's page itself on
hardware. A real Stagetimer room has been followed, on the simulator (the
Stagetimer bullet above).
### `docs/OSC.md` is generated — `npm run gen:osc-docs`
A published address space is a promise to somebody building a TouchOSC layout,
and they cannot check it short of trying every address at a switcher. So the
tables come from `oscDictionary(PARAMS)` — the same call the resolver uses —
and `test/osc.test.js` fails when the checked-in file stops matching. Edit the
prose in `tools/gen-osc-docs.mjs`; never edit the tables.
`src/core/osc-dictionary.js` is what widens the space: mynah ships the seven
layer parameters it can vouch for, and the control surface's `catalogue.json`
adds sixty-seven read off a real device. Regenerating that catalogue against
different firmware changes the document with nobody editing prose, which is the
point of the ids being structural.
- **Console, Timeline, Layer, Groups, Pixel Map, Surfaces and UMD are tabs in
the vendor's strip** on Screens / Aux. (`ui/tabs.js`), cloned from a real tab
exactly as `Shell` clones a sidebar entry. The strip's container carries a CSS-modules hash, so it is found by
**structure** — the parent of `.ui.tabular.menu` — never by name. React
re-renders that subtree on every selection change; a MutationObserver puts
the tabs back, and `_mount()` is idempotent because it runs constantly.
⚠️ **`.ui.tabular.menu` is not unique to that panel.** Preconfig heads its
page with a strip built from the same Semantic UI classes, and Console and
Timeline were appended to it for a release — two words in a row of glyphs, on
a page they have nothing to do with. A strip only qualifies if it holds a
**pane switcher**: at least two anchors that carry words and have no `href`.
That is the difference between "these tabs change what is shown here" and
"these links go somewhere else", and it needs no class, route or label. The
label is an `h5` on LivePremier and a bare text node on Midra — see the
platform section.
⚠️ **The strip runs out of room, and on LivePremier it always has.** Each
tab tries icon and label, label, `short`, then icon alone; when even the
icons don't fit, as many as do are shown in `order` and the rest go behind a
⋯, which is ours (it carries `data-lpp-more`) and opens a menu of its own over
the page.
On Web RCS 6.2.73 the panel is a fixed 360px whatever the window, the vendor
centres the strip in it and its collapse button `»` takes the right-hand
24px, so about 312px is usable and Properties and Memories spend 244 of it:
the result is ⋯ alone (66ae17b, measured on the simulator and the RS4). So
the fit is measured as **the strip's rect against the panel's, short of the
`»`**, never `scrollWidth` against `clientWidth`: the strip is centred, so it
spills off the left as well as the right, and it can be narrower than the
panel and still run under the `»`. The icon rung ran 426px, off both sides.
- **Settings are in the Preconfig flyout** (`ui/settings-panel.js`), beneath the
device's own System page, because Preconfig is where Web RCS files things
about the installation as a whole. Two groups of them are real settings now —
the console language pair and the OSC listener — and they are **server-side**
(`src/core/settings.js`, `PUT /__lpp/settings`, one file in `~/.livepremier-plus`).
Not `localStorage`, for two reasons that are not preferences: the OSC listener
is a UDP socket in the server process, and the Console exists in two windows
at once, so a per-page setting would have the tab and the popout disagreeing
about which language the operator chose. They are also **not keyed by device**
— re-pointing at a backup frame mid-show must not change the command language
or close a port a lighting desk is sending to. `Shell` takes `submenuOf: ''`
for this. The flyout's active class **cannot be lifted off a live element** the
way the sidebar's can — it exists only while the operator is on a page inside
the flyout, and they may never go to one — so it is read out of the vendor's
own stylesheet (`classFromStylesheets`). A proxied page is same-origin, so
`cssRules` is legible.
- **MIDI Mapping is anchored under Virtual RC400T**, not in the PLUS section.
`Shell` entries take an optional `after: ''` for this. The
anchor is matched on the visible **label**, because that is the only part of
the sidebar markup the vendor has not hashed.
- **The VPU map and the memory banks stay in PLUS** — both are whole-device
views, and everything else belongs to a part of the app that already exists.
The banks earn it: master memories cover every screen at once, and the screen
bank is one flat list of 1000 slots that any screen may recall from, so
filing them per-screen would be filing them wrongly.
### Memories and layer properties (`plugins/memories/panel.js`, `ui/properties-panel.js`)
Web RCS has a Memories tab and a Properties tab already, and these do not
replace them. They exist because **a vendor pane cannot be popped out.** `#root`
carries `__reactContainer$…` / `__reactEvents$…`: React 17+ delegation, with
every listener bound to that one container. Move the pane's DOM into a second
window and React keeps *updating* it — it holds node references and does not
care which document they are in — but every click dies, because the native
event bubbles to the popout's document and never reaches `#root`. Their `AwTab`
is `renderActiveOnly` too, so the pane is unmounted the moment you switch tabs.
Do not spend another afternoon looking for a way round this; there isn't one
that does not mean patching React internals.
So the banks and the properties are read from the mirror instead:
- **`core/memories.js`** covers all the banks — three on either platform, not
the same three (Midra has an aux bank and no layer bank). They are not
variations on one idea — what separates them is what a recall has to *name*:
master names only a slot, screen names a destination too, layer names a
destination and a layer. The set and the spellings come from `core/dialect.js`.
⚠️ **A save is not the mirror image of a recall.** On recall the slot comes
first (`…/load/slotList/items//screenList/…`); on save it comes **last**
(`…/save/screenList/items/S1/presetList/items/PROGRAM/slotList/items//…`).
Assuming symmetry produces a path the device accepts into nowhere: a write
that reports success and saves nothing.
- **`core/properties.js`** renders nothing by hand. The sections, types, ranges
and enum members all come out of `vendor/surface/catalogue.json`, which the
MIDI mapper already generated from a device's own bundle — 67 layer
parameters in twelve groups. Regenerate the catalogue and the panel grows the
new properties on its own.
⚠️ **Except the source list, which is the switcher's, not the enum's.** The
enum is every source the platform could have — 482 on LivePremier — and an
Aquilon RS4 with 24 inputs was offered all 256. `offeredValues` narrows a
*picker* by the dialect's `sourceOffered`, the vendor picker's own rule
(inputs and stills available, enabled and `USED` in the **applied
preconfig**, screens in `FREESTYLE`; on Midra, `isAvailable`), then by the
kind of layer (`LAYER_SOURCE_TYPES`: NATIVE takes background sets only, an
aux layer no colour, screens only on a split-mode layer), and always
keeps what the layer holds. `valuesFor` — what a write is checked against —
stays the whole enum, so a cue, a group or the Console naming a source that
has gone is still sent and the device judges it. Do not narrow the write.
⚠️ **Layer selection is not device state.** There is no `isSelected` anywhere in
the store and nothing in the catalogue; the vendor's Properties tab follows a
React selection we cannot read. So ours makes you name a destination, a buffer
and a layer. That is also why the tab is called **Layer** and not Properties —
two tabs with one name in the same strip is worse than a name that is only most
of the truth.
⚠️ **You address a LETTER, never PROGRAM or PREVIEW**, and which letter is on
air changes on every take. `bankLetter()` is the only sanctioned conversion; it
reports `settled: false` mid-take and the panel **refuses the write** rather
than guessing, because the wrong choice during a transition lands on the
output. A buffer that is on air gets a red banner saying so.
### Layer groups and the send-to menu (`core/groups.js`, `plugins/layer-groups/`, `plugins/send-to/`, `ui/preset-lock.js`)
A group is several layers — one screen or many — driven as one, kept per
device beside the cue stack. Two halves, and only one of them writes on its
own: `sourceCommands()` fans a source out when a caller asks, and
`createGang()` *follows*, writing the rest of a group into line when any
member changes by any route. The gang was **the first thing in this app to
put a write on the wire without an operator having asked for that write
specifically**, so read `core/groups.js`'s head before changing it. It has
company now — Layer Lock's follower, Surfaces' follower, Aux follow's follower,
Preview lock's padlock and the EDID builder's auto-fill — and the README's Safety
section lists each with its fence.
⚠️ **You gang a ROLE, not a letter.** Two screens are routinely on opposite
letters — S1 at `AT_UP` has program B while S2 at `AT_DOWN` has program A — so
a change seen in one screen's letter is turned back into program-or-preview
through `presetBanks()` and re-resolved per target. Copying letter to letter
puts a preview edit on air on half the screens. LivePremier's third buffer
(`presetPrevious`, C) is neither role and propagates nothing.
⚠️ **Three separate things stop it looping**, and they are not
interchangeable — the comment in `core/groups.js` says which case each closes.
The echo-suppression map is the one that is easy to think redundant: a fan-out
to three members produces a *second* round off its own first echo without it,
because that echo lands while the other members are still stale in the mirror.
`the echo of a fan-out produces no second round` failed before it existed.
⚠️ **The gang never fires on state it merely found.** `Session` replays the
frames buffered during hydration without dispatching them, so a page opening
onto a desk already out of step does not rewrite it. Opening a browser tab is
not an instruction to the switcher.
⚠️ **A layer belongs to at most one group**, imposed by `normalise()` on the
way in and out. Two ganged groups sharing a member is the one shape that could
still ping-pong, so it cannot be stored even by editing the file by hand.
**The `…` on a source card is cloned from the vendor's own `⋮`**, wrapper and
all — same reasoning as `ui/shell.js`'s sidebar entries, and the wrapper is
what makes it appear on hover. The glyph is swapped to `more-horizontal-12` so
the two are distinguishable. ⚠️ **A card does not say which source it is**: no
data attribute, no id, and the visible number is a position. What it has is a
picture, and `/api/device/snapshots/inputs/3` *is* `LIVE_3` — `dialect.
sourceFromSnapshot()` is that mapping read backwards, and a card it cannot
name gets no button, which is why the background-sets tab has none.
⚠️ **The PGM padlock is not device state.** The whole store was searched on
2026-09-21: the only `lock` keys are `frontPanel/pp/lock` and the ST2110 PTP
`isLocked`. `localStorage` is empty too. It is React state in the vendor
bundle, which means a socket write ignores it and that respecting it is a
choice — and that it can only be read where it is drawn. `ui/preset-lock.js`
falls back card → master pair → **locked**, because a screen whose card is not
on screen is the one case that cannot be checked and so must be the one that
asks.
### Layer Lock and partial takes (`core/layer-lock.js`, `plugins/layer-lock/`, the hook's gate)
The switcher has **no per-layer take and no layer lock** — searched for in
the 6.2.73 store and the vendor bundle on 2026-09-23. A take swaps whole
buffers. Each preset layer has a `transition` node (opening/closing effect,
flags `FORCE_TRANSITION` "avoid cross transition", `FORCE_CROSS`,
`DEPTH_CUT_*`), which chooses *how* a layer changes, never *whether*.
`xCopyProgramToPreview` exists but is whole-screen.
Both features stand on one fact: **a layer identical in program and preview
has nothing to transition.** Lock = keep preview equal to program; take only
= make every other layer equal, take, put their preview looks back.
The device's own verdict is `…/layerList/items//status/pp/up|down` —
`OFF`/`OPEN`/`CLOSE`/`CROSS`/`FLYING`/… ("Layer will do a … transition", the
vendor's comment). A real Aquilon C capture read `CROSS` for LIVE_2 vs LIVE_8
at the same geometry and `OFF` for NONE in both. ⚠️ **The simulator reports
`OFF` for every layer always**, so it cannot confirm a lock; and **no real frame
has been asked about a locked layer with a live source.** Which of up/down is
"next" is inferred (AT_DOWN → up) and unconfirmed.
Four things are load-bearing:
- ⚠️ **The hook now has an outbound gate, one of the two things in this app
between the vendor's UI and its socket** (Surfaces' shaper is the other). `hook.setGate(fn)`: `fn(raw,
release)` returning true holds the frame; the hook sends it itself after
750 ms whatever the gate does, sends at most once, and a throwing gate lets
the frame straight through. That cap lives in `ws-hook.js`, not the plugin,
on purpose — a plugin bug may delay a TAKE, never swallow one. The lock
engine holds only a take on a destination whose locked layers are out of
line; an in-line take is untouched. There is one gate, not a list; a second
user needs a design, not a second `setGate`. Surfaces needed to REWRITE
frames rather than hold them, and got that design: the **shaper** beside the
gate (see Surfaces below), which runs first.
- ⚠️ **Echoes are matched on path AND value.** Found on the simulator: a
recall writes preview L1, the lock writes the same path back, and the
recall's echo arrives first — path-only matching released the TAKE before
the lock's write was acknowledged. The switcher echoes a write in ~3.5 ms.
- **A second TAKE while one is held queues behind it** — with the fix already
mirrored it would find nothing to hold, go first, and the held one would
take twice.
- **The follower is the gang's cousin and keeps its rules**: role not letter,
nothing mid-take, only on live frames (never on found state — except when a
lock is *set*, which is the operator asking), and convergent because only
differing properties are written.
⚠️ **Only takes leaving this page are gated.** Front panel, T-bar (a stream
of positions — there is no honest moment to hold one), `server/osc.js`'s AWJ
take, Companion speaking AWJ, another browser. The panel says so on every
render. Proven on the simulator only (2026-09-23): lock + follower, a
recall-and-vendor-TAKE in one tick, take-only on one and on two screens.
### Transitions per layer and across a screen (`core/transitions.js`, `plugins/transitions/`, Take only) — **experimental**
Every layer of every preset buffer has its own transition, on both platforms
and under the same catalogue ids: `transition.opening`/`closing` (effect and
way), `timing.opening`/`closing` (a window, 0–65535 of the take), `speed.type`.
Only the take's **duration** belongs to the screen, and a memory recall
replaces it. There is no per-layer take. Two features stand on that, both
behind the Experimental features switch because no frame has shown them:
- **Take only with a time and an effect** (Layer Lock, "Take only with"). The
held layers have nothing to transition, so the screen's take time is the
moving layers' own. The engine writes the effect to the moving layers'
**preview** copies before the take, the time **last, straight before the
trigger** (the timeline's order), and puts each direction's own time back
in a `finally`, landed or not — a time written mid-take does not change the
running take. The effect stays on the layer (now program): Take only never
writes program. `client.js` strips `tenths`/`effect` while the switch is
off, for the panel and the `locks` service alike.
- **The Transitions tab** (`plugins/transitions/`, its own plugin,
`experimental: true`). One destination, one card per fitted layer, three
ways to write the ticked layers (the same effect, a move, a style). Every
write is a click: no gate, no follower, so it needs neither of the hook's
two seats — and because the settings are in the buffer before the take,
they apply to a take from anywhere, front panel and T-bar included.
The rules that are load-bearing:
- ⚠️ **Seconds are a view, never stored.** A window is a fraction of the take
time, and a recall changes that time. The tab works seconds out on every
render and turns typed seconds into units against the time **as it is when
the edit is committed** — and against the **next take's direction**, as Web
RCS's own Timing panel does: `takeUpTime` at `AT_DOWN` or on the way up,
`takeDownTime` otherwise (`takeTenths`). Styles keep the switcher's units.
- **The letter is resolved at the moment of writing** (`bankLetter`), and
nothing is written mid-take. PRW by default; PGM is offered on purpose,
with a warning, because which copy a CLOSING is read from is unknown and
finding out needs a way to write the copy on air.
- ⚠️ **A click handler reads the view when it runs, not when it was drawn.**
Found in the browser on 2026-10-19: the move was changed to "Whole take",
the click landed on the button from the previous repaint (panels repaint
about once a second), and its closure ran a wipe. Every button in the tab
reads `view` at click time; `test/transitions.test.js` clicks a stale one.
- **The moves assume a WIPE runs inside its layer's own box.** That is the
only reason a wipe across the screen needs working out: each layer's
window is where a line crossing the canvas passes over it, with a linear
speed so the edge does not ease at every layer boundary. Opening windows
come from preview's rectangle, closing from program's.
- **Speeds are spelt per platform** (`LINEAR_TRANSITION` / `LINEAR`): a style
keeps the word, `speedValue` spells it. The layer property offers six
effects; the enum's `WIPE_ADVANCED` is not one of them.
- **Not `rc400t-transition` for an icon**: that sprite id is a 160×21 drawing
of the RC400T's panel and draws as a blank sliver. The tab uses the fade
icons.
Run on the 6.2.73 simulator only (`test/sim/transitions.sim.test.js`, and the
tab driven in a browser through the demo): every write read back over AWJ in
the buffer meant, a 1.5 s take-only on a 0.3 s screen ran its 1.5 s and the
screen got 0.3/0.4 s back, the effect on the moved layer only. What only a
frame can answer is in `docs/NOTES.md` (2026-10-19): which copy a closing is
read from, what `timing.ratio` does, whether a wipe stays in its box, what the
force flags do to a layer that only swaps source, and whether windows behave
the same on a T-bar.
### Preview lock during takes (`plugins/preview-lock/`, `ui/preset-lock.js`)
**Mid-take, PREVIEW is the buffer arriving on program.** Both platforms
resolve the role against the transition state (the suffix rule in
`core/dialect.js`), so a recall to PREVIEW sent while `EFFECT_FROM_*` /
`COPY_FROM_*` is running loads the picture that is fading up, and it rides
the take to air. An operator who presses TAKE and then recalls the next look
straight away does exactly this.
**The fix is the vendor's own padlock, pressed for them — not a lock of
ours.** Web RCS 6.2.73's Redux `presetLockMiddleware` refuses the vendor UI's
screen, aux, layer and master memory loads into a locked role, with its own
warnings (`raiseScreenAuxMemoryLoadWarning`). The lock is Redux state keyed
by **role per screen** (`lock[PRESETMODE][screenAux]`), or the MST
`remoteStore.live.screens.presetModeLock` when remote selection is on. A
`.click()` on the card's padlock button goes through the vendor's own handler,
so the vendor's state, icon, master-pair display and warnings all follow.
`cardPadlock()` hands back the card's button and never the master pair, which
would lock every screen on the page.
Load-bearing:
- **Lock on the outbound TAKE frame, not on the status echo.** The take
leaving the page is the earliest moment there is; the status echo is the
fallback for takes from anywhere else. `xCut` is not a reason — no window.
- **Release only at rest, and only once the take happened** (seen in flight,
or resting at the other end). A take this page sent that never starts is
released after `START_GRACE_MS`, or a refused take leaves PRW shut for
good. There is deliberately **no cap while in flight**: a T-bar parked half
way has preview half on air.
- **Only ever open a padlock this page shut.** Shut before the take: the
operator's. Opened mid-take: overridden, left alone. Card gone when the take
lands: owed, opened when it is next drawn — otherwise a page change leaves
PRW locked with nobody knowing why.
- ⚠️ **Press the padlock in a microtask, never inside the send.** Web RCS
sends its own writes from INSIDE its Redux reducer — 6.2.73's root reducer
wrapper `awStore` diffs the device state and calls
`deviceStoreManager.notifyChange` → `_sendToServer` while Redux is still
dispatching (Midra 4K 3.2.29's bundle has the same wrapper). The hook hands
that frame to the plugin synchronously, so a `.click()` there runs the
padlock's toggle mid-dispatch and Redux refuses it ("Reducers may not
dispatch actions", error #9) inside the click's listener, where the browser
reports it and `.click()` returns as if it worked. That is why the vendor's
own TAKE button never shut the padlock while a TAKE from `session.send` did
(found 2026-10-17). `setPadlock` queues the press, and presses only if the
padlock still reads the other way; a press that leaves it open is logged as
"did NOT lock", never as the operator opening it. **The same applies to
anything that clicks a vendor control or dispatches into the vendor's store
from an outbound frame** — defer it out of the send.
- ⚠️ **The padlock stops the vendor's buttons, not the switcher**, so our own
recall paths hold themselves back through the `preview-lock` service:
`holdFor(ids)` / `holdWrites(cmds)` answer null (send now — exactly the old
behaviour) or a promise that the takes landed. The cue engine
(`CueStack({ hold })`), the Memories panel and the Console (`hold` option,
popouts reaching it through `bridge.services`) all ask. **A hold that gives
up (take time + `HOLD_GRACE_MS`) means do not send** — never "send anyway",
which is the failure itself. A recall into PROGRAM is never held.
- ⚠️ **The cue engine holds the whole cue and keeps GO order.** Holding only
the recall would let the cue's own TAKE go first and take the previous
preview to air. And a cue fired while an earlier one is waiting, or is
inside its `SETTLE_MS` with its TAKE not yet sent, queues behind it and asks
the hold only after that TAKE — asked earlier it sees a destination at
rest and overwrites the look about to be taken. This relies on an outbound
frame reaching the guard synchronously inside `send()` (hook → transport →
session `frame`). Without a hold the engine is byte-for-byte the old
synchronous one; the existing cue tests run that path.
- Companion, OSC and the front panel are still not reached.
**Midra 4K / Alta 4K (Midra 4K Simulator 3.2.29, 2026-10-06).** The failure
is real there: TAKE (5 s) then a recall to PREVIEW 0.6 s later loaded the UP
buffer while `EFFECT_FROM_DOWN` ran, and the memory was on program when the
take landed. Unlike the LivePremier sim, the Midra sim pushes the in-flight
state (`EFFECT_FROM_*` ~20 ms after `xTake`), so the guard's status path is
exercised there. The padlocks exist with the same sprites and `aria-pressed`,
but the page has no `.aw-preset-view`/`h2`: `cardPadlocks()` reads them
padlock first (`live-content-header__c__lock___` → its header's PGM/PRW label →
the nearest ancestor with exactly one `S`/`A` chip). Before that fix the
plugin logged "card not on screen" on every Midra take and shut nothing. The
Midra lock is per component (`isPresetLocked` disables that buffer's memory
drop target, source pickers, layer moves and properties-panel Load), not one
middleware, and a fresh Midra page draws every padlock open, PGM included.
A recall also overwrites `takeTime` with the memory's `transitionDuration`
mid-take without changing the running take — so a hold's deadline must be
read before any recall, as `whenSettled` does.
Proven on the LivePremier simulator (2026-10-06) with the page socket's
`send` replaced by a catcher: the plugin's click shut S1's PRW; a vendor
Memories ▸ Screen ▸ Load into PRW on S1+S2 sent only S2's recall; after the
take landed it sent both. Two cues fired back to back through the live
Timeline plugin with `session.send` caught: recall, TAKE, nothing through a
simulated take, then the second recall and TAKE once it landed. Not run on a
frame, a Midra or an Alta.
### Pixel Map (`plugins/pixel-map/`, `ui/preset-lock.js`)
An image from the switcher's library drawn into the vendor's own screen
cards, over the canvas, as a mask. It writes into the middle of Web RCS's
markup, like the layer names, and four things about it are load-bearing:
- **Between the layers and the handles, never on top.** Inside the raster
(`.aw-background-black` in the card's `.react-transform-component`) the
stack is `.aw-relative > .aw-absolute > [layers, handles]`, and the handles
group is only mounted while a layer is selected — React appends it, so it
lands after the map. On top of the handles, a mask blacks out the very
thing the operator needs to grab. A stack of another shape gets the map on
top and `describe().top` counts it.
- **`pointer-events: none` on the box and the picture**, `aria-hidden`, not
draggable. Hit-testing is what proves it: `document.elementFromPoint`
through a map lands on the vendor's `canvas-item`, and a real click through
S2's map selected S2's layer (6.2.73 sim, 2026-10-16).
- **The picture is `/api/device/images/download/`, never a snapshot.**
That is the original file (the 256×144 `snapshots/images_library/` is
only the TIFF fallback), and the Thumbnail relay rewrites every
`/api/device/snapshots/` `` inside a `.aw-preset-view`. `?v=`
busts the browser's cache on a re-upload; the switcher ignores the query.
- **The panel's `busy()` is "pointer down", not "focus inside".** A `