# 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 `` holds the swap instead, since a replaced dropdown closes. Typed text is kept only **until it is committed** — Enter, a `change`, leaving the field — which `trackFields` follows at the capture phase: after that the panel's value is the truth, or the Console's line never clears and a value the switcher clamped shows as typed (both happened; the first version kept typed text for as long as the field had focus). Measured 2026-09-23: before it, every text field and dropdown in the Edit page, Memories, Matrix Routing, Pitch, Companion, Timeline and Layer was replaced within 2.6 s of being focused. "Counterpart" is the field's `data-lpp-key` if it has one, else its shape and position — give a field in a list whose rows can move under the caret a key. Do not add another per-panel "busy while focused" flag for this; and never focus a field on every render, the way the Console used to — it stole the caret from the vendor's own fields once a second. - **Every panel is drawn by a test — `test/panel-render.test.js`.** Against an empty store and the simulator's, twice each (a render and a repaint), with the dependencies `main.js` gives it, over a small stand-in DOM (`test/helpers/fake-dom.js`). It exists because the Timeline took an option called `actions` that a function of its own shadowed: the first cue holding a plugin's action threw on every render and left an empty tab, and nothing noticed, because nothing rendered the panel. Moving panels into plugins is exactly the change that breaks a render without breaking an import — a new panel, or a plugin's page half, goes in that test. - **Take the stream marker before fetching the snapshot**, not after. See `core/session.js` and [docs/TRANSPORT.md](docs/TRANSPORT.md). Getting this backwards makes the mirror quietly stale in a way nothing reports. - **Do not update the mirror optimistically on send.** The device echoes every accepted write, and taking the echo as truth is what stops a rejected or clamped value showing as applied. - **Screens and auxiliaries share `screenAuxGroupList` for takes but split into `screenList` / `auxiliaryList` under `presetBank`.** An aux recall addressed through `screenList` is accepted and does nothing. - **Transition times are in tenths of a second**, and they are a property of the screen rather than an argument to the take. - **A TAKE in the same cue as a recall waits `SETTLE_MS` (150 ms).** Recalls are silent and take time to land; a TAKE that overtakes its own preset load transitions the *previous* preview contents to air. Wrong picture, on air, no error anywhere. The gap is a floor, not a guarantee, and it is skipped for a cue with nothing in flight. The standalone `webrcs-timeline` engine hit this independently against the simulator and landed on the same figure. - **The VPU panel never writes.** Every property it reads is `readOnly` in the device's own model. Keep it that way; the tool's value on a show floor depends on being provably harmless. - **The VPU model is vendored, not written here.** `src/vendor/vpu-model.js` is a copy of aquilon-vpu-map's `public/vpu.js`; edits belong upstream, and `npm run sync:vpu-model` brings them back. Anything this extension needs that the model lacks goes in `core/vpu.js`, which only adapts the device store into the record shape the model expects. - **`NATIVE` is a layer, not a background.** It is the first entry of the device's `PRECONFIG_SCREEN_LAYER` enum, a layer slot that consumes mixers and is counted by `layerCount`. Backgrounds live in `preconfig/backgrounds/` and cost no mixer at all. Calling `NATIVE` a background in the UI was wrong and is the confusion to avoid — there is a test pinning the wording. - **Auxiliaries do not use the VPU.** `usedInScreen` draws on an S1–S24 enum with no `A*` entries, and `preconfig/resources` has no aux list (an aux's `mode` and `auxCapability` are staged under `preconfig/resources/new/outputList`, which the UMD section uses, but they take no mixers). Do not add an aux column to the VPU panel. - **Optimized mode belongs to the whole VPU**, not to the screen that triggered it, and it removes the four-link scaling-engine boundary. Drawing that boundary on an optimized VPU shows a constraint the device is not applying. - **Everything the server says goes through the logbook** (`server/logbook.js`). `index.js` makes one, `createProxy` and the plugin host take it, and a plugin's `ctx.log` is `logbook.for(id)`: `ctx.log(msg)` as ever, with `.debug`, `.warn` and `.error` beside it and JSON-able data as a second argument. Not `console.log`: that reaches stdout, which under the desktop app is the launcher's last thirty lines, gone at Stop, and no user can send it. A line is on disk when `write` returns (synchronous on purpose: the last line before a crash is the useful one), at most 200 a second, and a disk that cannot be written costs the file and never the app. Debug lines stay in memory unless Settings → Logs → Detail says Detailed or `--log`/`LPP_LOG` was given (which wins). Every line is scrubbed of Tailscale keys and `password=…` pairs and the export's settings are `redact()`ed, but that is the net, not the plan: don't log a secret in the first place. A connection that can drop logs each drop with how long it lasted and what was heard on it (`grid-link.js`'s `#logEnd`), because "it keeps dropping" is answered by timings, not by the last error. ## Traps that cost time here - **The simulator the fixtures came from has no VPU at all.** It reports a `vpuLayerList` of 32 scalers, every one OFF, and no `vpuMixerList` (`$vpuLayer` answers `E12` on 6.2 hardware; on 6.1.60 it exists, every scaler at its defaults). Use `tools/harness.html` with the live capture instead. The panel names this case explicitly rather than drawing an empty chassis. **Not every simulator:** the rack's 6.2.73 under Wine (2026-10-13), and the simulator app's own Session 1 (Cmax), report a fully fitted C MAX — 64 mixers, all available, two enabled for S1/NATIVE — and `test/sim/screen.sim.test.js` checks `readSide` against it mixer by mixer. Neither case is evidence about hardware. ⚠️ **Nor is the empty shape only a simulator's:** an Aquilon RS4 on 6.1.60 (2026-10-16), screens on air, reports it exactly. `inspectMapping` calls it `unreported` and the panel words it from the device's own `isSimulated` — never from the shape, or a live switcher gets called a simulator. It is not the store's doing: over AWJ `$vpuMixer` answers E12 and every scaler reads its enum defaults, and the 6.1.60 page never reads `vpuLayerList` itself. What 6.1.x reports is per screen (`readScreenLayers`: layer sizes, staged room), and the panel shows that table under the explanation. The room is the box's pool, so `sharedRoom` says it once under the table when every screen agrees, and a column appears only if they ever don't (d450ed7). - **There is a 6.1.x simulator, and it is the RS4's page.** The AW LivePremier Simulator's package manager (the version button on a session) installs older firmware beside 6.2.73; 6.1.60 is installed on Allan's Mac as Session 2 (C+, `NLC_CPLUS`). Its web client is `app.80837794a672b9e2107f.js`, the bundle an Aquilon RS4 on 6.1.60 serves, and its store has the same empty VPU shape. A fresh session has **no screens in service**, so nothing has layer geometry until a preconfig is built; the Save Master Memory slot box is a bounded `AwNumberInput` that exists regardless. Both sessions use port 3000, so run one at a time. - **The Browser pane blocks cross-origin requests when the tab is on the LAN.** Injecting the modules from a local dev server works against a page on localhost and fails with `ERR_BLOCKED_BY_CLIENT` against a real device, with the request never reaching the server. That is the harness's reason to exist. - **The sidebar separator's padding lives on an inner title element**, not on the separator itself. Writing `textContent` to the wrapper loses the indent and the heading sits flush to the edge while the vendor's are inset. - **The keep-alive only fires after three seconds of silence.** A live device chatters every second, so waiting for a ping to identify the socket will wait forever. Adoption happens on the first Analog Way frame instead. - **React owns the sidebar and re-renders it.** A MutationObserver puts the section back rather than fighting reconciliation. - **The Console must hand mynah `facts`, not only `osc.buffer`.** mynah's `Set` — a layer parameter, a Midra audio layer — asks `facts.buffer` and `facts.canvas`; the OSC resolver asks `osc.buffer`. Until 0.7.0 the Console supplied only the second, so every mynah `Set` typed at it was refused with "needs a live connection" beside a live connection. `runContext()` now supplies both from the store mirror. - **"Not a secure context" has two causes, and the second is us.** Web MIDI and `getUserMedia` exist only on https and loopback. The launcher can bind the server to a LAN interface and then opens `http://:/` — served by this app, on this machine, insecure. `server/local-client.js` answers it: a LAN-bound server also listens on `127.0.0.1` (not on a wildcard bind, which already includes it — a second bind there fails on Linux), and a top-level navigation whose TCP source address equals its destination address is 302'd to loopback. Same-address-at-both-ends is the test, not "one of our addresses": a NAT'd VM's traffic arrives from a gateway address we own and would be sent to its own 127.0.0.1. Never redirect a fetch or an upgrade; the Web RCS's own requests must land where they were sent. `src/core/secure-context.js` is the one sentence the three panels show, and it names the page that is open, not the switcher. - **A Midra take with *preset toggle* off settles late.** The device passes `EFFECT_FROM_x` and then `COPY_FROM_x` before `AT_y`, so fire → settled is takeTime + ~250 ms on real hardware (the simulator, toggle on, sends only `EFFECT_` and lands on time). Wait for the `AT_` state, never for the clock. - **A Midra multiviewer recall touches widgets the model does not have.** Recalling a layout re-syncs `widgetList/items/17..27/control/pp/size*` to their status on a Pulse 4K (`widgetValidity` is 1–16). Invisible, and not a fault of ours — but a store diff after a recall will show it. - **Never re-recall an operator's modified preview to tidy a header.** A buffer whose `isModified` is true holds unsaved work; restoring it means saving it to a spare slot and recalling that, not recalling its `memoryId`. The header then reads `M --`, which is the honest price. ## Testing `npm test` — about 1,100 tests, no network, no browser. Nine run against a real Aquilon C capture (`aquilon-c-live-resources.json`, read 2026-08-21: seven in `live.test.js`, two in `core.test.js`) and are the only coverage of fitted mixers, output links and Optimized mode, none of which the fixtures' simulator produces. Five more run against an RS4's (`aquilon-rs4-6.1.60-resources.json`, 2026-10-16): the shape of a box that reports no mixer map, and its per-screen sizes and pool. `test/dialect.test.js` runs both object models against real stores — the Aquilon's memories capture and `midra-3.2.29-pulse4k.json`, cut from the Midra 4K simulator after the writes it asserts had been made through the mng dialect's own paths, so every mng path in it is one a switcher accepted. Forty-seven cover the proxy, against a stand-in Web RCS on a **real socket** rather than a mock — deliberately, because every bug worth catching there lives in the plumbing (headers, encodings, streaming, the upgrade handshake) and a mocked `http.request` would simply agree with whatever the code did. Both framing bugs above were found this way. ⚠️ **"No network" is enforced, because it was not true.** From 2026-08-22 to 2026-10-17 `osc.test.js` sent a real `xTake` on S1 to 127.0.0.1:10606 on every run. It never passed its pretend device's port, and it accepted "reached the device" as a pass. With a simulator on the same Mac, which is most days here, that was an unexplained TAKE a second after any session's `npm test` (`docs/NOTES.md`, 2026-10-17). `npm test` now preloads `test/helpers/offline.js` (`node --import … --test`). It refuses a connection from any test to a port that real kit this app drives listens on (AWJ, Web RCS, HyperDeck, Companion, UCenter, the routers), on any host, and fails the file with the stack that dialled. A pretend device goes on port 0 and its port is passed in; a device that is not there goes on port 1. A new test file goes in the script's list, after the `--import`. **Assert order, not a stopwatch.** macOS can hold a background `node --test` process's socket wake-ups to its next timer tick, a second late: a pretend switcher that answers in 1.5 s read 2.75 s, with the process idle in a CPU profile (2026-10-31, `snapshot-keeper.test.js`). Assert that the page was answered before the switcher sent, not that it took under so many milliseconds. ⚠️ **Every change is run on Windows and Linux before it lands, not only on a Mac.** Every Windows build up to 0.18.9 served the vendor UI with none of the panels: `path.normalize` turned `/__lpp/src/main.js` into `\src\main.js` there, the `/src/` check refused it, and every one of our files was a 404 (2026-11-03, `ownSourceFile` in `server/proxy.js`). Nothing caught it because nothing ran there; `npm test` on a Mac could not. Allan's rule since: test LPP work on **winlab** (Windows 11, `ssh winlab`, Edge, Chrome and Firefox) and the **kde-lab** Linux VM (Ubuntu 24.04, `ssh kdelab`, Chromium and Firefox), both VMs on lilnasX (`virsh list` there), as well as the Mac. Run the server the way the desktop app does (`LPP_PORT`, `LPP_HOST`, `LPP_DEVICE` against the rack simulator) and load it in each browser, through the debugging port and a tunnel when the box is headless. A code path that touches the filesystem asks its question with `path.win32` in a test too, so a Mac run fails the way Windows would. A page in a **hidden** browser (the desktop app's browser pane when it is not shown, a background tab) runs no animation frames, so the app's repaint (`throttleFrame` in `src/main.js`) waits until it is shown: a card that looks stale there is not a bug until a visible or headless browser agrees (found 2026-11-05, chasing the X-keys card). `LPP_SIM=: npm run test:sim` — the live suite in `test/sim/`, against a running LivePremier simulator. It boots the real app (`createProxy`, as `server/index.js` does) on a loopback port with a throwaway data directory and drives it the way the outside world does; `test/sim/harness.js` is the whole of the plumbing. AWJ is asked at the simulator's own address on 10606, or on `LPP_SIM_AWJ_PORT`. The rules it keeps, which a new file must keep too: - **It refuses anything that is not a simulator.** `startApp` asks the device over AWJ (`deviceList/items/1/pp/isSimulated`) before the app is pointed at it. There is no override. Every test passes `{ skip: SKIP }`, so an unset `LPP_SIM` is a skip with a reason, which is what CI sees. - **The witness is AWJ, not the app.** `Link` mirrors the vendor socket through the proxy (inbound frames only, tagged `dir` as `page-socket.js` tags them); `awjGet` asks the switcher on 10606, a path the app's own code is not on. Check a write there, not only in the mirror. - **Put back what you change.** `guardScreen` snapshots a screen's side, fade times and every buffer and restores them with the app's own `bufferWrites`; `Journal` records-then-writes per path; memories go in empty slots at the top of the bank (`spareSlots`) and are deleted after. Never save a **master** memory: it rewrites each screen's `bankSlot`, default slot 1. - **The simulator is shared**, so files run one at a time (`--test-concurrency=1`). The rack's has one screen in use (S1, one fitted layer); the simulator app's Session 1 has S1 and S2. - **What the simulator cannot show, skip with a reason; never pass on it.** It reports no state while a take is in flight (`transition` holds, then lands; `tbarPosition` jumps), so nothing gated on "mid-take" can be reached; it does nothing with `xStepBack`; and it echoes in about 5 ms, far quicker than hardware. The memory import and export hand the device a path on *its* filesystem, so against a simulator on another machine they answer the device's own `ERROR_INVALID_FILE` / `ERROR_INVALID_PATH` — the suite asserts that refusal, and the success only when the simulator is on loopback. - **Triggers latch, and the suite re-arms them.** An `x…` property reads true once fired; `Link.rearm()` (called by `guardScreen`'s restore) writes back false every trigger that read false before, which does nothing else. A recall also leaves the buffer flagged as an unmodified memory; `guardScreen` clears that by nudging one property and putting it back. - **The vendor's EDID save goes through the EDID editor** (`system/edid/edit`) and leaves its EDID there; `io.sim.test.js` journals the editor and restores its derived status too (docs/NOTES.md has the recipe). - **A write the switcher already holds is never echoed**, and it confirms a layer's source twice (`source/pp` then `source/status/pp`, not always together). `Link.waitFor` checks the current value first; `previewLook` waits for both, or the trailing echo lands in the next test's window. `LPP_CONSOLE= LPP_SIM= npm run test:console` — the console suite in `test/console/`, for a Pixelhue console on the desk (`docs/PIXELHUE.md`, "Testing it on a console", has the run and what a U5 mini is expected to have). `LPP_CONSOLE_MODEL` is `u5mini` (the default), `u5pro` or `u5`; a U5 or U5 Pro serves UCenter on loopback only, so the suite runs on the console. Each run writes what it saw to `test/console/results/` (gitignored) for folding into fixtures afterwards. It is `test/sim/`'s harness with a console in the loop, and keeps every rule above, plus four: - **Nothing else may listen to the console.** Every UCenter client acts on every press. `assertNoOtherDriver` asks the LivePremier Plus on :8535 and :8536, and any in `LPP_CONSOLE_PEERS`, what it drives and refuses if one shares the console (an instance on any other port, the demo's :8545 say, is not asked); `assertQuiet` refuses if anything republishes over the model. On 2026-10-16 the tray app on :8536 was holding the Mac's own UCenter with its panel on and pointed at a frame in use — an injected TAKE there would have taken on that frame. - **The console's witness is a socket of the suite's own**, a second `client-type=5` connection (`Witness`), not the app's state. Keys are found by `keyMode` in the console's own key map and bus keys by what they show, so no test spells a key code. - **An injected press is not a thumb.** `2-keys` proves UCenter and the app agree; only `3-hands` (`LPP_CONSOLE_GUIDED=1`, a person at the terminal) proves the key under a finger is the key the map says. - **The stand-in proves the suite runs, nothing more.** `LPP_CONSOLE=stand-in` is `test/helpers/fake-ucenter.js` on 127.0.0.1:8088. Never quote a pass against it as evidence about a console, and never teach it a behaviour nobody has seen. It serves the mini's socket path only and answers the U5's with the 200 a real mini gave: a stand-in that shares the app's mistake hid the wrong path until a user's mini found it. For the panels themselves, `tools/harness.html` — see the README. It proxies the vendor stylesheet from a named device so the panels are judged in the real design system, and no vendor asset is committed here. Verified through the proxy against LivePremier Simulator 6.2.73 on 2026-08-21: the vendor app boots, the hook lands ahead of the bundle, the store mirrors live, both panels render, the setup flow works, and a cue stack survives a reload. **Cue persistence had never once executed before that** — the extension's `chrome.storage` broker was never exercised. Still thinly covered on LivePremier hardware: an Aquilon RS4 (6.1.60) took one preview opacity from the Layer tab on 2026-10-16, and an Aquilon C mini (6.2.73) on 2026-10-30 took the Layer tab, Memories, the Console, the timeline's GO, Preview lock, Layer Groups and Send-to, Surfaces, Pixel Map, Audio Matrix, OSC input, arithmetic and Variables, and the Background Slicer (written and undone), each read over AWJ and the store diffed afterwards. The panels were opened against a live Aquilon C on 2026-09-10, and the Console's lines typed at a live Pulse 4K on 2026-09-13 are the other panel writes to real hardware; see the README's Status. The launcher has never been run as a real native tray window (its bundled chain was verified headlessly — embedded Node, staged app, proxying with injection). ## Related work `~/Projects/video/aquilon-vpu-map` reads the same VPU mapping over AWJ from a server. Same problem, opposite end: it reaches the device directly and runs headless; this has the whole device store for free but only inside a tab. Since 20e09f1 the two share one model: `src/vendor/vpu-model.js` is that project's `public/vpu.js`, refreshed by `npm run sync:vpu-model` and checked by `test/vendor.test.js`. There is no record adapter any more (`toMixerRecords()` went in that commit), so captures do not cross over; offline captures stay aquilon-vpu-map's job. This app's AWJ path (`server/awj.js`) is one-shot and never feeds the mirror — see the argument above. `~/Projects/video/webrcs-timeline` is a Rust workspace covering the same cue ground — `awj-proto`, `awj-link` (both transports) and `awj-cue`, 58 tests, verified against the simulator. It is the headless, show-critical path; this is the in-browser one. **The two cue engines are currently independent implementations of the same model and will drift.** Converging them is an open decision, not an oversight — see the note in the project memory. Its integer-thousandths cue numbering is worth adopting here if cue numbers ever become keys rather than labels. Derivation notes and the raw device captures live in a separate private research repo, not here, and that separation is deliberate now that this one is public. Keep it: nothing describing how the device model was arrived at belongs in this repository. `launcher/` is the fleet's standard Tauri shell (see `~/Projects/tooling/av-launcher`), retargeted via `src-tauri/launcher.toml` alone. No Rust was changed and none should need to be. ## Notes `docs/NOTES.md` carries this repo's working notes — current status, decisions already made, and the traps that have actually bitten. Read it before changing anything non-obvious. Cross-cutting fleet knowledge lives in [fleet-notes](https://github.com/stoatworks-labs/fleet-notes).