weed-cli 2.4.4__tar.gz → 2.4.5__tar.gz

{weed_cli-2.4.4/weed_cli.egg-info → weed_cli-2.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weed-cli
-Version: 2.4.4
+Version: 2.4.5
 Summary: Censorship-resistant video PoC — discovery/hosting/download over signed relay events, a real Kademlia DHT, or a TLS-capable NAT-traversal tunnel
 License: MIT
 Keywords: p2p,video,censorship-resistant,discovery,dht,kademlia,nat-traversal
@@ -55,6 +55,8 @@ output (not simulated) — see [Status](#status) for what's verified.
   - [CLI](#cli)
   - [Interactive shell](#interactive-shell)
   - [Web UI](#web-ui)
+  - [Orbit Visualizer](#orbit-visualizer)
+  - [Orbit Visualizer plugins](#orbit-visualizer-plugins)
   - [Docker](#docker)
 - [Core mechanisms](#core-mechanisms)
 - [The integrated node](#the-integrated-node)
@@ -185,9 +187,19 @@ browser opened with that token gets the **party view** and nothing
 else — the live Orbit stream, what's playing, a vote on which
 downloaded track plays next (one vote per person per track, toggleable),
 and whatever links you set. The admin's **Party** tab holds the guest
-link and its QR code, the title and links, the live tally with a ▶ per
-track, and an "auto-play the top vote when a track ends" switch.
+link and its QR code, the title and links, the live tally with a ▶ and
+a ♫+ (add to playlist) per track, and an "auto-play the top vote when a
+track ends" switch. The guest page itself is bare: the live picture and
+"now playing" pinned to the top, the vote list scrolling beneath —
+alphabetical, with an iPod-style A–Z strip down the right edge to jump
+by letter, and a "leading:" line for the current front-runners.
 Guests can't host, download, like, subscribe, or read the library.
+Switch on **guest chat** in the Party tab and everyone gets a message
+box: the last few messages are drawn over the picture — into the
+visualizer's canvas, so the stream carries them to VLC, a Roku and the
+guest page's picture alike (the visualizer's 💬 toggles that), and as
+an overlay on the plain player window. Messages live in memory only
+(the last 200), one per second per person, 200 characters each.
 
 `--stream-plain-port` adds a plain-HTTP listener that serves *only* the
 stream endpoints (the Orbit MJPEG stream and downloaded files), for
@@ -201,17 +213,44 @@ Includes real HTTP range support (`/api/stream/<job_id>`) so a
 `<video>` tag can seek a completed download instead of downloading it
 blind.
 
-The visualizer's 🎹 panel binds an AKAI MPK mini (or any Web MIDI
-controller) to modes, transitions and sliders; **export** saves the
-keymap as a `.json` file and **import** loads one, so a layout travels
-between browsers and machines.
-
-The player's ⇄ button is **video swap**: pick another download whose
-picture stands in for the current track's — for an mp3 or a
-static-image video, so the visualizer (and the player window) have real
-footage. The audio stays with the track; the borrowed video loops on its
-own, follows play/pause, and the choice is remembered per track in the
-browser.
+### Orbit Visualizer
+
+The player's 🌀 button opens the **Orbit Visualizer**: a canvas driven by
+the track's audio (Web Audio analyser) and a low-res sample of its
+picture. Eleven built-in modes — Tunnel, Bars, Mirror, Scope, Spiral,
+Pixels, ASCII (six character sets, natural or neon), Plasma, Kaleido,
+Particles, Freefall — plus the ten in `web/orbit_extras.js` (next
+section). Click the lit mode again for the plain video. Speed, React and
+Zoom retune every mode; every setting persists in the browser.
+
+- **Fade**: the transition between modes and between tracks — Burn,
+  Warp, Glitch, Pixelate, Crossfade, Wipe, the plugin ones, or Random
+  (the ⚄ button picks which ones Random may draw from), with a length
+  slider. A transition can declare its own length multiple (Win95's
+  crash runs at 3×).
+- **Navigation**, Blender-style: scroll zooms, left-drag pans,
+  middle-drag rotates, shift+middle pans, ctrl+middle zooms,
+  double-click resets. `f` fullscreen, ←/→ cycle modes (fullscreen),
+  shift+1-9,0 jump to a mode, ↑/↓ ASCII brightness, `[`/`]` resolution.
+- **Network stream** (📡): the canvas goes out as MJPEG on
+  `/api/orbit-view` for VLC (`vlc --demux=mjpeg --network-caching=300
+  <url>`; 🔗 copies the URL, token included), a Roku IP-camera viewer,
+  or the guest party page. Resolution and JPEG quality are selectable;
+  the ⏱ slider delays the local audio by up to 10 s to line up with a
+  laggy viewer. The stream keeps running while the visualizer is closed,
+  minimised to PIP, or in a background tab. Picture only — audio stays
+  wherever the browser is playing it.
+- **MIDI** (🎹): an AKAI MPK mini or any Web MIDI controller
+  (Chrome/Edge/Firefox). Pads pick modes and fire actions, knobs turn
+  the sliders or sweep through modes/transitions/character sets;
+  endless encoders are detected on their own. Every row, plugin modes
+  and transitions included, has a Learn button; **export** saves the
+  keymap as a `.json` file and **import** loads one.
+- **Video swap** (⇄ on the player): another download's picture stands
+  in for the current track's — for an mp3 or a static-image video, so
+  the visuals have real footage. Audio stays with the track; the
+  borrowed video loops on its own, follows play/pause, and the pairing
+  is remembered per track.
 
 ### Orbit Visualizer plugins
 
@@ -444,8 +483,13 @@ just designed:
 - Transitive trust through the subscribe graph
 - NAT traversal via relay-mediated tunneling, with TLS and heartbeat
 - Kademlia DHT discovery, survives the announcing node going offline
-- Local web UI with live progress, QR onboarding, and HTTP range streaming
-- Containerized node (`Dockerfile.node`, `docker-compose.node.yml`)
+- Local web UI with live progress, QR onboarding, HTTP range streaming,
+  optional two-tier token auth, and the guest party page with voting
+- Orbit Visualizer: 21 modes and 16 transitions behind a plugin API,
+  MJPEG network stream (VLC/Roku), Web MIDI control with keymap files,
+  video swap — 44 Playwright tests against real Chromium (`tests/e2e/`)
+- Containerized node (`Dockerfile.node`, `docker-compose.node.yml`),
+  with `web/` bind-mounted so frontend edits need no rebuild
 
 ## Known limitations
 
@@ -484,3 +528,7 @@ mechanisms hold up:
   and votes are anonymous per browser cookie — enough to put a
   LAN-bound UI behind something and hand guests a safe subset, not a
   reason to face it at the internet.
+- The Orbit stream is picture only, as MJPEG: fine for VLC, an
+  IP-camera app or the party page, but no audio travels with it and
+  there's no HLS/MP4 endpoint, so a stock Roku or smart-TV player
+  can't take it directly.

{weed_cli-2.4.4 → weed_cli-2.4.5}/README.md

@@ -23,6 +23,8 @@ output (not simulated) — see [Status](#status) for what's verified.
   - [CLI](#cli)
   - [Interactive shell](#interactive-shell)
   - [Web UI](#web-ui)
+  - [Orbit Visualizer](#orbit-visualizer)
+  - [Orbit Visualizer plugins](#orbit-visualizer-plugins)
   - [Docker](#docker)
 - [Core mechanisms](#core-mechanisms)
 - [The integrated node](#the-integrated-node)
@@ -153,9 +155,19 @@ browser opened with that token gets the **party view** and nothing
 else — the live Orbit stream, what's playing, a vote on which
 downloaded track plays next (one vote per person per track, toggleable),
 and whatever links you set. The admin's **Party** tab holds the guest
-link and its QR code, the title and links, the live tally with a ▶ per
-track, and an "auto-play the top vote when a track ends" switch.
+link and its QR code, the title and links, the live tally with a ▶ and
+a ♫+ (add to playlist) per track, and an "auto-play the top vote when a
+track ends" switch. The guest page itself is bare: the live picture and
+"now playing" pinned to the top, the vote list scrolling beneath —
+alphabetical, with an iPod-style A–Z strip down the right edge to jump
+by letter, and a "leading:" line for the current front-runners.
 Guests can't host, download, like, subscribe, or read the library.
+Switch on **guest chat** in the Party tab and everyone gets a message
+box: the last few messages are drawn over the picture — into the
+visualizer's canvas, so the stream carries them to VLC, a Roku and the
+guest page's picture alike (the visualizer's 💬 toggles that), and as
+an overlay on the plain player window. Messages live in memory only
+(the last 200), one per second per person, 200 characters each.
 
 `--stream-plain-port` adds a plain-HTTP listener that serves *only* the
 stream endpoints (the Orbit MJPEG stream and downloaded files), for
@@ -169,17 +181,44 @@ Includes real HTTP range support (`/api/stream/<job_id>`) so a
 `<video>` tag can seek a completed download instead of downloading it
 blind.
 
-The visualizer's 🎹 panel binds an AKAI MPK mini (or any Web MIDI
-controller) to modes, transitions and sliders; **export** saves the
-keymap as a `.json` file and **import** loads one, so a layout travels
-between browsers and machines.
-
-The player's ⇄ button is **video swap**: pick another download whose
-picture stands in for the current track's — for an mp3 or a
-static-image video, so the visualizer (and the player window) have real
-footage. The audio stays with the track; the borrowed video loops on its
-own, follows play/pause, and the choice is remembered per track in the
-browser.
+### Orbit Visualizer
+
+The player's 🌀 button opens the **Orbit Visualizer**: a canvas driven by
+the track's audio (Web Audio analyser) and a low-res sample of its
+picture. Eleven built-in modes — Tunnel, Bars, Mirror, Scope, Spiral,
+Pixels, ASCII (six character sets, natural or neon), Plasma, Kaleido,
+Particles, Freefall — plus the ten in `web/orbit_extras.js` (next
+section). Click the lit mode again for the plain video. Speed, React and
+Zoom retune every mode; every setting persists in the browser.
+
+- **Fade**: the transition between modes and between tracks — Burn,
+  Warp, Glitch, Pixelate, Crossfade, Wipe, the plugin ones, or Random
+  (the ⚄ button picks which ones Random may draw from), with a length
+  slider. A transition can declare its own length multiple (Win95's
+  crash runs at 3×).
+- **Navigation**, Blender-style: scroll zooms, left-drag pans,
+  middle-drag rotates, shift+middle pans, ctrl+middle zooms,
+  double-click resets. `f` fullscreen, ←/→ cycle modes (fullscreen),
+  shift+1-9,0 jump to a mode, ↑/↓ ASCII brightness, `[`/`]` resolution.
+- **Network stream** (📡): the canvas goes out as MJPEG on
+  `/api/orbit-view` for VLC (`vlc --demux=mjpeg --network-caching=300
+  <url>`; 🔗 copies the URL, token included), a Roku IP-camera viewer,
+  or the guest party page. Resolution and JPEG quality are selectable;
+  the ⏱ slider delays the local audio by up to 10 s to line up with a
+  laggy viewer. The stream keeps running while the visualizer is closed,
+  minimised to PIP, or in a background tab. Picture only — audio stays
+  wherever the browser is playing it.
+- **MIDI** (🎹): an AKAI MPK mini or any Web MIDI controller
+  (Chrome/Edge/Firefox). Pads pick modes and fire actions, knobs turn
+  the sliders or sweep through modes/transitions/character sets;
+  endless encoders are detected on their own. Every row, plugin modes
+  and transitions included, has a Learn button; **export** saves the
+  keymap as a `.json` file and **import** loads one.
+- **Video swap** (⇄ on the player): another download's picture stands
+  in for the current track's — for an mp3 or a static-image video, so
+  the visuals have real footage. Audio stays with the track; the
+  borrowed video loops on its own, follows play/pause, and the pairing
+  is remembered per track.
 
 ### Orbit Visualizer plugins
 
@@ -412,8 +451,13 @@ just designed:
 - Transitive trust through the subscribe graph
 - NAT traversal via relay-mediated tunneling, with TLS and heartbeat
 - Kademlia DHT discovery, survives the announcing node going offline
-- Local web UI with live progress, QR onboarding, and HTTP range streaming
-- Containerized node (`Dockerfile.node`, `docker-compose.node.yml`)
+- Local web UI with live progress, QR onboarding, HTTP range streaming,
+  optional two-tier token auth, and the guest party page with voting
+- Orbit Visualizer: 21 modes and 16 transitions behind a plugin API,
+  MJPEG network stream (VLC/Roku), Web MIDI control with keymap files,
+  video swap — 44 Playwright tests against real Chromium (`tests/e2e/`)
+- Containerized node (`Dockerfile.node`, `docker-compose.node.yml`),
+  with `web/` bind-mounted so frontend edits need no rebuild
 
 ## Known limitations
 
@@ -452,3 +496,7 @@ mechanisms hold up:
   and votes are anonymous per browser cookie — enough to put a
   LAN-bound UI behind something and hand guests a safe subset, not a
   reason to face it at the internet.
+- The Orbit stream is picture only, as MJPEG: fine for VLC, an
+  IP-camera app or the party page, but no audio travels with it and
+  there's no HLS/MP4 endpoint, so a stock Roku or smart-TV player
+  can't take it directly.

{weed_cli-2.4.4 → weed_cli-2.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "weed-cli"
-version = "2.4.4"
+version = "2.4.5"
 description = "Censorship-resistant video PoC — discovery/hosting/download over signed relay events, a real Kademlia DHT, or a TLS-capable NAT-traversal tunnel"
 readme = "README.md"
 license = { text = "MIT" }

{weed_cli-2.4.4 → weed_cli-2.4.5}/tests/test_web_ui_api.py

@@ -660,3 +660,50 @@ def test_request_with_no_origin_header_is_allowed(web_server):
     through (see web_ui.py's _check_origin docstring)."""
     status, resp = http_post_json(f'{web_server}/api/like', {'content_hash': 'd' * 64})
     assert status == 200
+
+
+def test_party_chat_is_gated_rate_limited_and_polled_by_id(web_server, monkeypatch):
+    """The party chat: off until the admin turns it on, one message a
+    second per person, 200 characters, guests and admin both post, the
+    ring is polled by id, and only the admin can wipe it."""
+    import web_ui
+    monkeypatch.setattr(web_ui, 'AUTH_TOKEN', 'admin-secret')
+    monkeypatch.setattr(web_ui, 'STREAM_TOKEN', 'guest-secret')
+    monkeypatch.setattr(web_ui, 'CHAT_MIN_INTERVAL', 0.3)
+    with web_ui._chat_lock:
+        web_ui._chat_messages.clear(); web_ui._chat_last_post.clear()
+    guest = {'Authorization': 'Bearer guest-secret'}
+    admin = {'Authorization': 'Bearer admin-secret'}
+
+    # off by default: readable, but nobody can post
+    status, headers, body = _raw_get(f'{web_server}/api/chat', guest)
+    assert status == 200 and json.loads(body) == {'enabled': False, 'messages': [], 'you': json.loads(body)['you']}
+    assert json.loads(body)['you'].startswith('guest-')
+    assert _raw_post(f'{web_server}/api/chat', {'text': 'hi'}, guest)[0] == 403
+    assert _raw_post(f'{web_server}/api/chat', {'text': 'hi'}, admin)[0] == 403
+    assert _raw_post(f'{web_server}/api/chat', {'text': 'hi'})[0] == 401     # no token at all
+
+    status, _, r = _raw_post(f'{web_server}/api/party/config', {'chat': True}, admin)
+    assert status == 200 and r['party']['chat'] is True
+    assert json.loads(_raw_get(f'{web_server}/api/party', guest)[2])['chat'] is True
+
+    voter = {**guest, 'Cookie': headers['set-cookie'].split(';')[0]}
+    status, _, r = _raw_post(f'{web_server}/api/chat', {'text': '  turn   it up  ', 'name': 'dave'}, voter)
+    assert status == 200 and r['message']['name'] == 'dave' and r['message']['text'] == 'turn it up' and r['message']['role'] == 'guest'
+    first_id = r['message']['id']
+    assert _raw_post(f'{web_server}/api/chat', {'text': 'again'}, voter)[0] == 429          # too fast
+    assert _raw_post(f'{web_server}/api/chat', {'text': '   '}, admin)[0] == 400
+    assert _raw_post(f'{web_server}/api/chat', {'text': 'x' * 201}, admin)[0] == 400
+    status, _, r = _raw_post(f'{web_server}/api/chat', {'text': 'no'}, admin)
+    assert status == 200 and r['message']['name'] == 'host' and r['message']['role'] == 'admin'
+
+    _, _, body = _raw_get(f'{web_server}/api/chat', voter)
+    msgs = json.loads(body)['messages']
+    assert [m['text'] for m in msgs] == ['turn it up', 'no']
+    _, _, body = _raw_get(f'{web_server}/api/chat?since={first_id}', voter)
+    assert [m['text'] for m in json.loads(body)['messages']] == ['no']
+
+    assert _raw_post(f'{web_server}/api/chat/clear', {}, voter)[0] == 401
+    status, _, r = _raw_post(f'{web_server}/api/chat/clear', {}, admin)
+    assert status == 200 and r['cleared'] == 2
+    assert json.loads(_raw_get(f'{web_server}/api/chat', voter)[2])['messages'] == []

{weed_cli-2.4.4 → weed_cli-2.4.5}/web_ui.py

@@ -77,13 +77,24 @@ AUTH_COOKIE_MAX_AGE = 30 * 24 * 3600
 # track rather than one per click; nothing else is keyed on it
 GUEST_COOKIE = 'weed_guest'
 _party_votes = {}      # content_hash -> set of guest ids (in memory; a restart clears the tally)
+# the party chat: a short in-memory ring of {id, name, text, ts, role}.
+# Guests and the admin post; the visualizer draws the last few over the
+# picture (so the stream carries them) and the guest page lists them.
+# Off unless the admin turns it on in the Party tab (party['chat']).
+CHAT_KEEP = 200
+CHAT_MAX_TEXT = 200
+CHAT_MIN_INTERVAL = 1.0   # seconds between posts, per person
+_chat_messages = []
+_chat_seq = 0
+_chat_last_post = {}      # guest id (or 'admin') -> last post time
+_chat_lock = threading.Lock()
 
 
 def _party_settings():
     """Caller must hold _lock. The library's 'party' dict, created on
     demand -- a library written (or a test fixture built) before this
     key existed simply doesn't have it."""
-    return _library.setdefault('party', {'title': '', 'links': [], 'autoplay': False})
+    return _library.setdefault('party', {'title': '', 'links': [], 'autoplay': False, 'chat': False})
 _orbit_ws_since = 0.0  # when the current stream started -- the party page keys its <img> on it
 # Optional second listener, plain HTTP, serving *only* the stream
 # endpoints (/api/orbit-view, /api/orbit-stream, /api/stream/<job>).
@@ -863,7 +874,7 @@ class Handler(BaseHTTPRequestHandler):
 
     # GET endpoints a guest (stream token) may use; everything else under
     # /api/ is admin-only. The stream endpoints also take ?token=.
-    _GUEST_GET = ('/api/orbit-view', '/api/orbit-stream', '/api/config', '/api/party')
+    _GUEST_GET = ('/api/orbit-view', '/api/orbit-stream', '/api/config', '/api/party', '/api/chat')
 
     def do_GET(self):
         parsed = urlparse(self.path)
@@ -910,6 +921,8 @@ class Handler(BaseHTTPRequestHandler):
             return self._json(cfg)
         if path == '/api/party':
             return self._handle_party()
+        if path == '/api/chat':
+            return self._handle_chat_get(qs)
         if path == '/api/discover':
             results = node.group_discover_by_content(node.discover(qs.get('relay') or [DEFAULT_RELAY]))
             return self._json({'results': results})
@@ -998,7 +1011,7 @@ class Handler(BaseHTTPRequestHandler):
         # /api/login is how a browser *gets* the cookie (the unlock
         # prompt); voting is the one thing a guest may POST; everything
         # else needs the admin token already
-        if path == '/api/party/vote':
+        if path in ('/api/party/vote', '/api/chat'):
             if not self._guest_ok():
                 return self._deny()
         elif path != '/api/login' and not self._authorized():
@@ -1036,6 +1049,7 @@ class Handler(BaseHTTPRequestHandler):
         handlers = {
             '/api/party/vote': self._handle_party_vote, '/api/party/config': self._handle_party_config,
             '/api/party/played': self._handle_party_played,
+            '/api/chat': self._handle_chat_post, '/api/chat/clear': self._handle_chat_clear,
             '/api/host': self._handle_host, '/api/host/forget': self._handle_forget_host,
             '/api/download': self._handle_download,
             '/api/like': self._handle_like, '/api/subscribe': self._handle_subscribe,
@@ -1339,7 +1353,7 @@ class Handler(BaseHTTPRequestHandler):
         plain = self._stream_plain_base()
         self._json({
             'role': self._role(), 'title': party.get('title') or '', 'links': party.get('links') or [],
-            'autoplay': bool(party.get('autoplay')),
+            'autoplay': bool(party.get('autoplay')), 'chat': bool(party.get('chat')),
             'now_playing': now_playing,
             'stream': {
                 'active': active, 'since': _orbit_ws_since,
@@ -1386,9 +1400,63 @@ class Handler(BaseHTTPRequestHandler):
                 party['links'] = links[:20]
             if 'autoplay' in body:
                 party['autoplay'] = bool(body.get('autoplay'))
+            if 'chat' in body:
+                party['chat'] = bool(body.get('chat'))
             _save_library()
             self._json({'ok': True, 'party': dict(party)})
 
+    # ── party chat ──────────────────────────────────────────────────
+    def _handle_chat_get(self, qs):
+        """GET /api/chat?since=<id>: whether chat is on, plus every message
+        newer than <since> (all of the ring when omitted)."""
+        gid, extra = self._ensure_guest_id()
+        try:
+            since = int((qs.get('since') or ['0'])[0])
+        except ValueError:
+            since = 0
+        with _lock:
+            enabled = bool(_party_settings().get('chat'))
+        with _chat_lock:
+            msgs = [m for m in _chat_messages if m['id'] > since]
+        self._json({'enabled': enabled, 'messages': msgs, 'you': 'host' if self._role() == 'admin' else 'guest-' + gid[:4]},
+                   headers=extra)
+
+    def _handle_chat_post(self, body):
+        """POST /api/chat {text, name?}: one message. Refused while chat is
+        off, over-long, empty, or faster than one a second per person."""
+        global _chat_seq
+        with _lock:
+            enabled = bool(_party_settings().get('chat'))
+        if not enabled:
+            return self._json({'error': 'chat is off'}, status=403)
+        gid, extra = self._ensure_guest_id()
+        role = self._role()
+        who = 'admin' if role == 'admin' else gid
+        text = ' '.join(str(body.get('text') or '').split())
+        if not text:
+            return self._json({'error': 'empty message'}, status=400)
+        if len(text) > CHAT_MAX_TEXT:
+            return self._json({'error': f'message too long (max {CHAT_MAX_TEXT} characters)'}, status=400)
+        name = ' '.join(str(body.get('name') or '').split())[:24] or ('host' if role == 'admin' else 'guest-' + gid[:4])
+        now = time.time()
+        with _chat_lock:
+            last = _chat_last_post.get(who, 0)
+            if now - last < CHAT_MIN_INTERVAL:
+                return self._json({'error': 'slow down'}, status=429)
+            _chat_last_post[who] = now
+            _chat_seq += 1
+            msg = {'id': _chat_seq, 'name': name, 'text': text, 'ts': now, 'role': role or 'admin'}
+            _chat_messages.append(msg)
+            del _chat_messages[:-CHAT_KEEP]
+        self._json({'ok': True, 'message': msg}, headers=extra)
+
+    def _handle_chat_clear(self, body):
+        """Admin: wipe the ring."""
+        with _chat_lock:
+            n = len(_chat_messages)
+            _chat_messages.clear()
+        self._json({'ok': True, 'cleared': n})
+
     def _handle_party_played(self, body):
         """Admin: a voted track got played -- clear its tally so the next
         vote starts fresh."""

{weed_cli-2.4.4 → weed_cli-2.4.5/weed_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: weed-cli
-Version: 2.4.4
+Version: 2.4.5
 Summary: Censorship-resistant video PoC — discovery/hosting/download over signed relay events, a real Kademlia DHT, or a TLS-capable NAT-traversal tunnel
 License: MIT
 Keywords: p2p,video,censorship-resistant,discovery,dht,kademlia,nat-traversal
@@ -55,6 +55,8 @@ output (not simulated) — see [Status](#status) for what's verified.
   - [CLI](#cli)
   - [Interactive shell](#interactive-shell)
   - [Web UI](#web-ui)
+  - [Orbit Visualizer](#orbit-visualizer)
+  - [Orbit Visualizer plugins](#orbit-visualizer-plugins)
   - [Docker](#docker)
 - [Core mechanisms](#core-mechanisms)
 - [The integrated node](#the-integrated-node)
@@ -185,9 +187,19 @@ browser opened with that token gets the **party view** and nothing
 else — the live Orbit stream, what's playing, a vote on which
 downloaded track plays next (one vote per person per track, toggleable),
 and whatever links you set. The admin's **Party** tab holds the guest
-link and its QR code, the title and links, the live tally with a ▶ per
-track, and an "auto-play the top vote when a track ends" switch.
+link and its QR code, the title and links, the live tally with a ▶ and
+a ♫+ (add to playlist) per track, and an "auto-play the top vote when a
+track ends" switch. The guest page itself is bare: the live picture and
+"now playing" pinned to the top, the vote list scrolling beneath —
+alphabetical, with an iPod-style A–Z strip down the right edge to jump
+by letter, and a "leading:" line for the current front-runners.
 Guests can't host, download, like, subscribe, or read the library.
+Switch on **guest chat** in the Party tab and everyone gets a message
+box: the last few messages are drawn over the picture — into the
+visualizer's canvas, so the stream carries them to VLC, a Roku and the
+guest page's picture alike (the visualizer's 💬 toggles that), and as
+an overlay on the plain player window. Messages live in memory only
+(the last 200), one per second per person, 200 characters each.
 
 `--stream-plain-port` adds a plain-HTTP listener that serves *only* the
 stream endpoints (the Orbit MJPEG stream and downloaded files), for
@@ -201,17 +213,44 @@ Includes real HTTP range support (`/api/stream/<job_id>`) so a
 `<video>` tag can seek a completed download instead of downloading it
 blind.
 
-The visualizer's 🎹 panel binds an AKAI MPK mini (or any Web MIDI
-controller) to modes, transitions and sliders; **export** saves the
-keymap as a `.json` file and **import** loads one, so a layout travels
-between browsers and machines.
-
-The player's ⇄ button is **video swap**: pick another download whose
-picture stands in for the current track's — for an mp3 or a
-static-image video, so the visualizer (and the player window) have real
-footage. The audio stays with the track; the borrowed video loops on its
-own, follows play/pause, and the choice is remembered per track in the
-browser.
+### Orbit Visualizer
+
+The player's 🌀 button opens the **Orbit Visualizer**: a canvas driven by
+the track's audio (Web Audio analyser) and a low-res sample of its
+picture. Eleven built-in modes — Tunnel, Bars, Mirror, Scope, Spiral,
+Pixels, ASCII (six character sets, natural or neon), Plasma, Kaleido,
+Particles, Freefall — plus the ten in `web/orbit_extras.js` (next
+section). Click the lit mode again for the plain video. Speed, React and
+Zoom retune every mode; every setting persists in the browser.
+
+- **Fade**: the transition between modes and between tracks — Burn,
+  Warp, Glitch, Pixelate, Crossfade, Wipe, the plugin ones, or Random
+  (the ⚄ button picks which ones Random may draw from), with a length
+  slider. A transition can declare its own length multiple (Win95's
+  crash runs at 3×).
+- **Navigation**, Blender-style: scroll zooms, left-drag pans,
+  middle-drag rotates, shift+middle pans, ctrl+middle zooms,
+  double-click resets. `f` fullscreen, ←/→ cycle modes (fullscreen),
+  shift+1-9,0 jump to a mode, ↑/↓ ASCII brightness, `[`/`]` resolution.
+- **Network stream** (📡): the canvas goes out as MJPEG on
+  `/api/orbit-view` for VLC (`vlc --demux=mjpeg --network-caching=300
+  <url>`; 🔗 copies the URL, token included), a Roku IP-camera viewer,
+  or the guest party page. Resolution and JPEG quality are selectable;
+  the ⏱ slider delays the local audio by up to 10 s to line up with a
+  laggy viewer. The stream keeps running while the visualizer is closed,
+  minimised to PIP, or in a background tab. Picture only — audio stays
+  wherever the browser is playing it.
+- **MIDI** (🎹): an AKAI MPK mini or any Web MIDI controller
+  (Chrome/Edge/Firefox). Pads pick modes and fire actions, knobs turn
+  the sliders or sweep through modes/transitions/character sets;
+  endless encoders are detected on their own. Every row, plugin modes
+  and transitions included, has a Learn button; **export** saves the
+  keymap as a `.json` file and **import** loads one.
+- **Video swap** (⇄ on the player): another download's picture stands
+  in for the current track's — for an mp3 or a static-image video, so
+  the visuals have real footage. Audio stays with the track; the
+  borrowed video loops on its own, follows play/pause, and the pairing
+  is remembered per track.
 
 ### Orbit Visualizer plugins
 
@@ -444,8 +483,13 @@ just designed:
 - Transitive trust through the subscribe graph
 - NAT traversal via relay-mediated tunneling, with TLS and heartbeat
 - Kademlia DHT discovery, survives the announcing node going offline
-- Local web UI with live progress, QR onboarding, and HTTP range streaming
-- Containerized node (`Dockerfile.node`, `docker-compose.node.yml`)
+- Local web UI with live progress, QR onboarding, HTTP range streaming,
+  optional two-tier token auth, and the guest party page with voting
+- Orbit Visualizer: 21 modes and 16 transitions behind a plugin API,
+  MJPEG network stream (VLC/Roku), Web MIDI control with keymap files,
+  video swap — 44 Playwright tests against real Chromium (`tests/e2e/`)
+- Containerized node (`Dockerfile.node`, `docker-compose.node.yml`),
+  with `web/` bind-mounted so frontend edits need no rebuild
 
 ## Known limitations
 
@@ -484,3 +528,7 @@ mechanisms hold up:
   and votes are anonymous per browser cookie — enough to put a
   LAN-bound UI behind something and hand guests a safe subset, not a
   reason to face it at the internet.
+- The Orbit stream is picture only, as MJPEG: fine for VLC, an
+  IP-camera app or the party page, but no audio travels with it and
+  there's no HLS/MP4 endpoint, so a stock Roku or smart-TV player
+  can't take it directly.