docs(radar): subscribe to spokes only while displaying the radar (#3019)

* docs(radar): subscribe to spokes only while displaying the radar

A provider treats spoke subscribers as the measure of whether anyone is
watching a radar and may let an unwatched one stand down. Spell out that
clients open the stream only while showing the radar, and that a relaying
provider holds its upstream subscription only while it has subscribers of
its own, using binaryStreamManager.getClientCount.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015VvpP3eXB2WhgD8bwyDWoU

* docs(radar): show the spoke socket being closed, name the stream id

* docs(radar): fix the connection example introduction

---------

Co-authored-by: Claude Code <noreply@anthropic.com>

Author: keesverruijt

.gitignore

@@ -59,4 +59,6 @@ nul
 
 # debug artefacts
 *.sln
-test/server-test-config/debug
+test/server-test-config/debug
+# Per-developer local Makefile (deploy shortcuts, scratch targets)
+Makefile.local

docs/develop/rest-api/radar_api.md

@@ -83,6 +83,12 @@ Different manufacturers have vastly different hardware capabilities, control set
 1. **Capabilities** — hardware capabilities (Doppler, dual-range, no-transmit zones, supported ranges)
 2. **Controls** — schema for each control (type, valid values, modes, read-only status)
 
+A provider also treats the spoke stream's subscribers as the measure of whether anyone is
+watching a radar, and may let an unwatched radar stand down. A plugin that relays spokes from
+another provider — a proxy in front of mayara-server, say — must therefore hold its own
+upstream subscription only while it has subscribers of its own; see
+[Subscribe only while displaying](#subscribe-only-while-displaying).
+
 ## Control Categories
 
 | Category       | Description                  | Examples                                           |
@@ -994,7 +1000,9 @@ The URL is constructed by convention from the host serving the radar list:
 
 ### Connection Logic
 
-This a Javascript example how to set up the connection to receive spokes:
+This is a JavaScript example of how to set up the connection to receive spokes. It returns the
+socket so the caller can close it when the radar is no longer displayed (see
+[Subscribe only while displaying](#subscribe-only-while-displaying)):
 
 ```javascript
 async function connectToSpokes() {
@@ -1019,9 +1027,35 @@ async function connectToSpokes() {
     const spokeData = new Uint8Array(event.data)
     // Process binary spoke data...
   }
+  return socket
 }
+
+// When the radar view is hidden or unmounted:
+//   socket.close()
 ```
 
+### Subscribe only while displaying
+
+An open spoke stream tells the provider that someone is watching the radar. A provider may
+use that to stop holding an unwatched radar up: mayara-server, for instance, lets a radar
+stand down once nobody has subscribed to its spokes for the period set by its `autoStandby`
+control (a minute by default), so that a headless installation does not keep the magnetron
+transmitting for nobody. Control PUTs and REST reads do not count as watching — only the
+spoke stream does.
+
+So a client must open the spoke stream only while it is actually displaying the radar, and
+close it as soon as it stops — when the radar view is hidden, not merely when the page is
+closed. A subscription held open "just in case" keeps the radar transmitting.
+
+The same rule applies one level up. A provider plugin that relays spokes from another
+source (the mayara-server plugin, or an app-specific bridge such as an ORCA emulator)
+must hold its upstream subscription only while it has subscribers itself, and close it
+when the last one leaves. On the server side `app.binaryStreamManager.getClientCount(streamId)`,
+with `streamId` being `` `radars/${radarId}` ``, gives the number of clients currently
+subscribed to that radar's spoke stream, so a relay can connect on the first subscriber and
+disconnect after the last. A relay that stays subscribed around the clock hides every
+downstream client from the provider, and the radar never stands down.
+
 ### Spoke content and the legend
 
 Every spoke contains `spoke_len` bytes. The radar API always uses one byte per pixel, with every byte representing a value explained by the `legend` contained in the capabilities.