From 90f5ab146c5123cc9356ab9a132661d93f67cd0f Mon Sep 17 00:00:00 2001
From: Adrian Hilber <LeeO86@users.noreply.github.com>
Date: Thu, 5 Nov 2026 03:09:45 +0100
Subject: [PATCH 1/5] 1.3.4: interaction preview sends every new picture, stuck
 closes logged and counted

The WebSocket preview waited 20 ms for a new preview and otherwise resent
the previous JPEG (about 2 new pictures a second on a busy page). It now
waits like preview.jpg (up to 100 ms) and never sends a session the same
picture twice. Stuck closes log websocket_stuck_close and count
websocket_stuck_closes_total{reason}. WebSockets keep at most 64 KiB
unsent (TCP_NOTSENT_LOWAT). Release 1.3.4: version, image tags, CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017ybuzgBaGxuB5UiaE8dRa4
---
 .github/workflows/container-codecs.yaml |  2 +-
 CHANGELOG.md                            | 12 ++++++++-
 CMakeLists.txt                          |  2 +-
 SPEC.md                                 |  5 ++--
 deploy/mxl-browser-source-gpu.yaml      |  2 +-
 deploy/mxl-browser-source.yaml          |  2 +-
 docker/docker-compose.demo.yaml         |  2 +-
 docker/docker-compose.host.yaml         |  2 +-
 docs/api.md                             |  2 +-
 src/app/api.cpp                         |  1 +
 src/app/application.cpp                 | 13 ++++++++--
 src/ops/counters.cpp                    |  1 +
 src/ops/httpserver.cpp                  | 25 ++++++++++++++----
 src/ops/httpserver.hpp                  | 11 ++++++--
 tests/integration/interact_test.py      | 34 ++++++++++++++++++++++---
 tests/integration/metrics_test.py       |  1 +
 tests/unit/test_counters.cpp            |  2 +-
 tests/unit/test_httpserver.cpp          | 15 +++++++++++
 18 files changed, 111 insertions(+), 23 deletions(-)

diff --git a/.github/workflows/container-codecs.yaml b/.github/workflows/container-codecs.yaml
index 00763c3..04c65b8 100644
--- a/.github/workflows/container-codecs.yaml
+++ b/.github/workflows/container-codecs.yaml
@@ -1,7 +1,7 @@
 name: Container (H.264/H.265)
 
 # The image variant with a CEF build that plays H.264 and H.265 (docs/proprietary-codecs.md).
-# A tag codecs-<version> (for example codecs-1.3.3) builds that commit and pushes
+# A tag codecs-<version> (for example codecs-1.3.4) builds that commit and pushes
 # <version>-codecs. Normal releases (v*.*.*) are not touched.
 on:
   push:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82435af..1ef7832 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,16 @@
 # Changelog
 
-## Image variant 1.3.3-codecs
+## 1.3.4 (2026-11-05)
+
+- **Interaction preview shows every new picture** (SPEC §7.3). The WebSocket preview waited only 20 ms for a new preview and otherwise sent the previous JPEG again: on a busy page (YouTube on test-all-gfx) about 2 of 9 frames per second were new, so the preview stood still for seconds. It now waits for the preview like `preview.jpg` (up to 100 ms), and a session never gets the same picture twice.
+  - Tests: `tests/integration/interact_test.py` (a moving page: no frame repeats the previous picture).
+- **Stuck closes are logged and counted** (SPEC §7.3, §12). A WebSocket closed because its client did not read (which ends interaction control) logs `websocket_stuck_close` with the client and reason and counts `websocket_stuck_closes_total{reason}` (`outbox_size`, `outbox_age`, `preview_not_taken`; at 0 from the start).
+  - Tests: `tests/unit/test_httpserver.cpp` (each reason reported once), `tests/unit/test_counters.cpp`, `tests/integration/metrics_test.py`, `interact_test.py`.
+- **Previews do not pile up in the kernel** (SPEC §7.3). WebSockets keep at most 64 KiB unsent (`TCP_NOTSENT_LOWAT`); on a slow path the server drops previews early instead of holding seconds of them in the send buffer, so the preview latency no longer grows and shrinks.
+
+## Image variant 1.3.3.2-codecs (2026-11-05)
+
+First image with H.264/H.265, built from 1.3.3; from 1.3.4 on every release also has `<version>-codecs`.
 
 - **H.264 and H.265 (proprietary codecs).** A second image, `<version>-codecs`, uses a CEF build of the same version with H.264 (`<video>`, MSE, WebRTC receive) and H.265 (`<video>`, MSE) decoding in software; the normal image cannot play them, so for example the WebRTC previews of other functions stayed black. The function itself is unchanged. **Licensing is the user's responsibility** ([`docs/proprietary-codecs.md`](docs/proprietary-codecs.md)).
   - `docker/Dockerfile` takes `CEF_URL` (default: the CEF project's build as before); `docker/cef-codecs/` holds the patches and the URL and SHA-1 of the build; a tag `codecs-<version>` runs `.github/workflows/container-codecs.yaml`.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index ff8b400..9b5b204 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,7 +1,7 @@
 cmake_minimum_required(VERSION 3.24 FATAL_ERROR)
 
 project(mxl-browser-source
-    VERSION 1.3.3
+    VERSION 1.3.4
     DESCRIPTION "MXL media function: a web page rendered offscreen with CEF"
     LANGUAGES CXX C
 )
diff --git a/SPEC.md b/SPEC.md
index 6c08507..d318244 100644
--- a/SPEC.md
+++ b/SPEC.md
@@ -387,8 +387,8 @@ Limits: 200 input messages per second per session, 64 KiB per message; beyond th
 The siblings preview with low-rate JPEG (multiviewer `/preview.jpg` at 5 fps and 480 px, test player thumbnail encoded on request). The browser source keeps that mechanism and adds a push path for interaction:
 
 - `GET /api/v1/preview.jpg`: the newest frame, converted after the request arrives (each request gets a ticket and is answered with a preview made for it or a later one; 1.1.0 answered with the previous request's picture), encoded once per preview.
-- Preview frames over the interaction WebSocket at `BROWSER_PREVIEW_FPS` (default 10, up to 25 while the session controls the page) and `BROWSER_PREVIEW_WIDTH` (default 960). A session asks for its rate with `preview` (a watcher can only lower it); the UI asks for 25 when its session gets control and for the default (`preview` without `fps`) when it loses it. The server also drops a session to at most `BROWSER_PREVIEW_FPS` when it loses control (toggle off, take-over, timeout), so only the controller can have more.
-- A client that stops reading never slows the others. Preview frames are sent without waiting: when a client's socket is full, its frame is dropped (the next one is newer; `preview_frames_dropped_total`), and a frame that has started goes out whole before anything else. Text messages (state, acks, errors, events) keep their order and are never dropped: what does not fit waits in a per-client outbox that the connection's own thread drains, so no sender ever waits for a client (state, cursor and console broadcasts come from the CEF UI thread, where a wait could trip the hang timeout). A client whose outbox holds more than 4 MiB or whose oldest message has waited 5 s, or that takes no preview frame for 5 s, is closed, which ends its control. This holds for `/api/v1/events` too. Polling a JPEG adds a round trip per frame; a push keeps the click-to-picture time short. WebRTC is not used: full-rate monitoring is mxl-webrtc-monitor's job (route the video flow to it).
+- Preview frames over the interaction WebSocket (each a preview made after it was due, waited for up to 100 ms like `preview.jpg`; a session never gets the same picture twice, 1.3.4) at `BROWSER_PREVIEW_FPS` (default 10, up to 25 while the session controls the page) and `BROWSER_PREVIEW_WIDTH` (default 960). A session asks for its rate with `preview` (a watcher can only lower it); the UI asks for 25 when its session gets control and for the default (`preview` without `fps`) when it loses it. The server also drops a session to at most `BROWSER_PREVIEW_FPS` when it loses control (toggle off, take-over, timeout), so only the controller can have more.
+- A client that stops reading never slows the others. Preview frames are sent without waiting: when a client's socket is full, its frame is dropped (the next one is newer; `preview_frames_dropped_total`), and a frame that has started goes out whole before anything else. Text messages (state, acks, errors, events) keep their order and are never dropped: what does not fit waits in a per-client outbox that the connection's own thread drains, so no sender ever waits for a client (state, cursor and console broadcasts come from the CEF UI thread, where a wait could trip the hang timeout). A client whose outbox holds more than 4 MiB or whose oldest message has waited 5 s, or that takes no preview frame for 5 s, is closed, which ends its control; such a close is logged (`websocket_stuck_close` with the client and reason) and counted (`websocket_stuck_closes_total{reason}`). The kernel keeps at most 64 KiB of a WebSocket unsent (`TCP_NOTSENT_LOWAT`), so on a slow path previews are dropped early instead of waiting seconds in the send buffer. This holds for `/api/v1/events` too. Polling a JPEG adds a round trip per frame; a push keeps the click-to-picture time short. WebRTC is not used: full-rate monitoring is mxl-webrtc-monitor's job (route the video flow to it).
 - The preview is made from the BGRA frame (downscaled box filter, composited over a checkerboard in the UI when transparent), so it costs nothing when no client watches.
 
 ## 8. NMOS
@@ -689,6 +689,7 @@ Prefix `mxl_browser_source_`. Durations in seconds with millisecond buckets.
 | `interaction_events_total` | counter | `type`, `result` (`ok`, `rejected`, `dropped`) |
 | `preview_frames_total` | counter | – (preview frames sent; until 1.3.1 also those a blocked client never took) |
 | `preview_frames_dropped_total` | counter | – (preview frames dropped because the client's socket was full, §7.3) |
+| `websocket_stuck_closes_total` | counter | `reason` (`outbox_size`, `outbox_age`, `preview_not_taken`; WebSockets closed because the client did not read, §7.3; 1.3.4) |
 | `devtools_sessions` | gauge | – |
 | `sender_enabled` | gauge | `sender` |
 | `nmos_registered` | gauge | – |
diff --git a/deploy/mxl-browser-source-gpu.yaml b/deploy/mxl-browser-source-gpu.yaml
index ee16029..7dbe970 100644
--- a/deploy/mxl-browser-source-gpu.yaml
+++ b/deploy/mxl-browser-source-gpu.yaml
@@ -60,7 +60,7 @@ spec:
           type: RuntimeDefault
       containers:
         - name: browser-source
-          image: ghcr.io/leeo86/mxl-browser-source:1.3.3
+          image: ghcr.io/leeo86/mxl-browser-source:1.3.4
           env:
             - name: NMOS_HOST_ADDRESS
               valueFrom:
diff --git a/deploy/mxl-browser-source.yaml b/deploy/mxl-browser-source.yaml
index 7d7bb7a..4ba72d2 100644
--- a/deploy/mxl-browser-source.yaml
+++ b/deploy/mxl-browser-source.yaml
@@ -53,7 +53,7 @@ spec:
           type: RuntimeDefault
       containers:
         - name: browser-source
-          image: ghcr.io/leeo86/mxl-browser-source:1.3.3
+          image: ghcr.io/leeo86/mxl-browser-source:1.3.4
           env:
             - name: NMOS_HOST_ADDRESS
               valueFrom:
diff --git a/docker/docker-compose.demo.yaml b/docker/docker-compose.demo.yaml
index 2544d35..389f20a 100644
--- a/docker/docker-compose.demo.yaml
+++ b/docker/docker-compose.demo.yaml
@@ -21,7 +21,7 @@ services:
       - ./registry.json:/home/registry.json:ro
 
   browser-source:
-    image: ${MBS_IMAGE:-ghcr.io/leeo86/mxl-browser-source:1.3.3}
+    image: ${MBS_IMAGE:-ghcr.io/leeo86/mxl-browser-source:1.3.4}
     network_mode: host
     user: "1000:1000"
     shm_size: 1gb
diff --git a/docker/docker-compose.host.yaml b/docker/docker-compose.host.yaml
index e49db6e..4deb461 100644
--- a/docker/docker-compose.host.yaml
+++ b/docker/docker-compose.host.yaml
@@ -4,7 +4,7 @@
 # GPU: add -f docker/docker-compose.gpu.yaml.
 services:
   browser-source:
-    image: ${MBS_IMAGE:-ghcr.io/leeo86/mxl-browser-source:1.3.3}
+    image: ${MBS_IMAGE:-ghcr.io/leeo86/mxl-browser-source:1.3.4}
     network_mode: host
     user: "1000:1000"
     shm_size: 1gb
diff --git a/docs/api.md b/docs/api.md
index bd9a25c..3731e02 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -127,7 +127,7 @@ Our own routes:
 
 No token (the page asks for it). SPEC §10.6.
 
-`GET /widgets` → `[{"id":"interaction","title":"Browser interaction","params":{"type":"object","properties":{}},"min_size":{"w":640,"h":400},"version":"1.3.3"},{"id":"ograf","title":"OGraf graphics","params":{"type":"object","properties":{"layers":{"type":"string",…}}},"min_size":{"w":640,"h":480},"version":"1.3.3"}]`, with `Access-Control-Allow-Origin: <Origin>` when `WIDGET_FRAME_ANCESTORS` lists that origin (or `*`) and always `Vary: Origin`. Other methods: 405.
+`GET /widgets` → `[{"id":"interaction","title":"Browser interaction","params":{"type":"object","properties":{}},"min_size":{"w":640,"h":400},"version":"1.3.4"},{"id":"ograf","title":"OGraf graphics","params":{"type":"object","properties":{"layers":{"type":"string",…}}},"min_size":{"w":640,"h":480},"version":"1.3.4"}]`, with `Access-Control-Allow-Origin: <Origin>` when `WIDGET_FRAME_ANCESTORS` lists that origin (or `*`) and always `Vary: Origin`. Other methods: 405.
 
 `GET /widget/interaction[?theme=dark|light|transparent]` and `GET /widget/ograf[?theme=…&layers=1,2]` → the UI page with only the interaction window, or the Graphics tab's preview, layers and form (only the listed layers; no library, upload or delete; `docs/ograf.md` §8), `Content-Security-Policy: frame-ancestors <WIDGET_FRAME_ANCESTORS>`, no `X-Frame-Options`. A bad `theme`: 400; another id: 404. Other query parameters are ignored.
 
diff --git a/src/app/api.cpp b/src/app/api.cpp
index 856811b..0e035b2 100644
--- a/src/app/api.cpp
+++ b/src/app/api.cpp
@@ -395,6 +395,7 @@ namespace mbs::app
             return std::nullopt;
         }
         ops::WebSocketHandlers h;
+        h.stuck = [this](char const* reason) { _metrics.inc("websocket_stuck_closes_total", {{"reason", reason}}, 1); };
         if (req.path == "/api/v1/events")
         {
             h.open = [this](std::shared_ptr<ops::WebSocket> const& socket) {
diff --git a/src/app/application.cpp b/src/app/application.cpp
index bf21074..1c9b574 100644
--- a/src/app/application.cpp
+++ b/src/app/application.cpp
@@ -1473,9 +1473,12 @@ namespace mbs::app
 
     // Preview frames for the interaction sessions at their rates (SPEC §7.3): one JPEG per new
     // frame, sent to each session that is due. Nothing is converted while nobody watches.
+    // A session never gets the same picture twice: until 1.3.3 a preview that took longer than
+    // 20 ms was answered with the previous JPEG (about 2 new pictures a second on a busy page).
     void Application::previewLoop()
     {
         std::map<int, Clock::time_point> due;
+        std::map<int, std::uint64_t> shown; // per session: the preview sequence it got last
         std::vector<std::uint8_t> rgb;
         std::uint64_t sequence = 0;
         while (!_stopping.load())
@@ -1499,17 +1502,20 @@ namespace mbs::app
                 }
             }
             std::erase_if(due, [&](auto const& entry) { return rates.count(entry.first) == 0; });
+            std::erase_if(shown, [&](auto const& entry) { return rates.count(entry.first) == 0; });
             if (ready.empty())
             {
                 continue;
             }
+            // Waits for a preview made after this request, as preview.jpg does (at most 100 ms).
             auto const ticket = _engine->requestPreview();
-            for (int i = 0; i < 10 && !_engine->preview(ticket, rgb, sequence); ++i)
+            for (int i = 0; i < 50 && !_engine->preview(ticket, rgb, sequence); ++i)
             {
                 std::this_thread::sleep_for(std::chrono::milliseconds(2));
             }
             std::string jpeg;
             std::uint64_t grain = 0;
+            std::uint64_t jpegSequence = 0;
             {
                 std::lock_guard lock{_jpegMutex};
                 if (sequence != _jpegSequence && !rgb.empty())
@@ -1520,6 +1526,7 @@ namespace mbs::app
                 }
                 jpeg = _jpeg;
                 grain = _jpegGrain;
+                jpegSequence = _jpegSequence;
             }
             if (jpeg.empty())
             {
@@ -1536,9 +1543,11 @@ namespace mbs::app
                 std::lock_guard lock{_socketsMutex};
                 for (int id : ready)
                 {
-                    if (auto it = _interactSockets.find(id); it != _interactSockets.end())
+                    auto it = _interactSockets.find(id);
+                    if (it != _interactSockets.end() && shown[id] != jpegSequence)
                     {
                         targets.push_back(it->second);
+                        shown[id] = jpegSequence;
                     }
                 }
             }
diff --git a/src/ops/counters.cpp b/src/ops/counters.cpp
index f903f9f..4da6062 100644
--- a/src/ops/counters.cpp
+++ b/src/ops/counters.cpp
@@ -33,6 +33,7 @@ namespace mbs::ops
         zero(m, "console_messages_total", "level", {"debug", "info", "warning", "error"});
         zero(m, "ograf_uploads_total", "result", {"ok", "rejected"});
         zero(m, "ograf_restores_total", "result", {"ok", "error"});
+        zero(m, "websocket_stuck_closes_total", "reason", {"outbox_size", "outbox_age", "preview_not_taken"});
         for (auto const* action : {"load", "play", "stop", "update", "custom", "clear"})
         {
             for (auto const* result : {"ok", "error", "timeout", "unavailable"})
diff --git a/src/ops/httpserver.cpp b/src/ops/httpserver.cpp
index 1b10db0..321ebe8 100644
--- a/src/ops/httpserver.cpp
+++ b/src/ops/httpserver.cpp
@@ -3,6 +3,7 @@
 
 #include <arpa/inet.h>
 #include <netinet/in.h>
+#include <netinet/tcp.h>
 #include <poll.h>
 #include <sys/socket.h>
 #include <unistd.h>
@@ -16,6 +17,7 @@
 #include <cstring>
 #include <thread>
 
+#include "util/logging.hpp"
 #include "util/uuid.hpp"
 
 namespace mbs::ops
@@ -224,10 +226,13 @@ namespace mbs::ops
         return {};
     }
 
-    WebSocket::WebSocket(int fd, std::string peer)
+    WebSocket::WebSocket(int fd, std::string peer, std::function<void(char const* reason)> onStuck)
         : _fd(fd)
         , _peer(std::move(peer))
+        , _onStuck(std::move(onStuck))
     {
+        int const unsent = kUnsentBytes;
+        ::setsockopt(_fd, IPPROTO_TCP, TCP_NOTSENT_LOWAT, &unsent, sizeof(unsent));
     }
 
     WebSocket::~WebSocket() = default;
@@ -244,7 +249,7 @@ namespace mbs::ops
         _outboxBytes += _outbox.back().bytes.size();
         if (_outboxBytes > kOutboxBytes)
         {
-            fail();
+            stuck("outbox_size");
             return false;
         }
         flushLocked(now);
@@ -269,6 +274,16 @@ namespace mbs::ops
         _outboxBytes = 0;
     }
 
+    void WebSocket::stuck(char const* reason)
+    {
+        log::warn("websocket_stuck_close", {{"client", _peer}, {"reason", reason}, {"outbox_bytes", static_cast<std::uint64_t>(_outboxBytes)}});
+        if (_onStuck)
+        {
+            _onStuck(reason);
+        }
+        fail();
+    }
+
     void WebSocket::flushLocked(Clock::time_point now)
     {
         while (!_outbox.empty())
@@ -291,7 +306,7 @@ namespace mbs::ops
         }
         if (!_outbox.empty() && now - _outbox.front().queued >= kStuckTimeout)
         {
-            fail();
+            stuck("outbox_age");
         }
     }
 
@@ -304,7 +319,7 @@ namespace mbs::ops
         }
         else if (now - _droppingSince >= kStuckTimeout)
         {
-            fail();
+            stuck("preview_not_taken");
             return Sent::Closed;
         }
         return Sent::Dropped;
@@ -644,7 +659,7 @@ namespace mbs::ops
             {
                 return;
             }
-            auto socket = std::make_shared<WebSocket>(fd, req.peer);
+            auto socket = std::make_shared<WebSocket>(fd, req.peer, handlers.stuck);
             {
                 std::lock_guard lock{socketsMutex};
                 std::erase_if(sockets, [](auto const& w) { return w.expired(); });
diff --git a/src/ops/httpserver.hpp b/src/ops/httpserver.hpp
index 187c058..6d630cf 100644
--- a/src/ops/httpserver.hpp
+++ b/src/ops/httpserver.hpp
@@ -50,17 +50,21 @@ namespace mbs::ops
     /// outbox holds more than kOutboxBytes or its oldest frame is older than kStuckTimeout.
     /// Binary frames (previews) are dropped instead of queued when the socket is full (the next
     /// one is newer); one that has started is finished first. A client that takes no binary
-    /// frame for kStuckTimeout is closed too.
+    /// frame for kStuckTimeout is closed too. Such a "stuck" close is logged and reported to
+    /// `onStuck` with its reason (outbox_size, outbox_age, preview_not_taken).
+    /// The kernel keeps at most kUnsentBytes unsent (TCP_NOTSENT_LOWAT), so a slow path drops
+    /// previews early instead of holding seconds of them in the send buffer.
     class WebSocket
     {
     public:
-        WebSocket(int fd, std::string peer);
+        WebSocket(int fd, std::string peer, std::function<void(char const* reason)> onStuck = {});
         ~WebSocket();
         WebSocket(WebSocket const&) = delete;
         WebSocket& operator=(WebSocket const&) = delete;
 
         static constexpr std::chrono::milliseconds kStuckTimeout{5000};
         static constexpr std::size_t kOutboxBytes = 4 * 1024 * 1024;
+        static constexpr int kUnsentBytes = 64 * 1024;
 
         enum class Sent
         {
@@ -92,6 +96,7 @@ namespace mbs::ops
         bool flush();
         // With _sendMutex held:
         void fail();
+        void stuck(char const* reason); // logs, reports and closes
         void flushLocked(Clock::time_point now);
         Sent dropped(Clock::time_point now); // counts towards kStuckTimeout
 
@@ -101,6 +106,7 @@ namespace mbs::ops
         bool _dropping = false;
         Clock::time_point _droppingSince;
         std::string _peer;
+        std::function<void(char const*)> _onStuck;
         std::mutex _sendMutex;
         std::atomic<bool> _open{true};
     };
@@ -110,6 +116,7 @@ namespace mbs::ops
         std::function<void(std::shared_ptr<WebSocket> const&)> open;
         std::function<void(std::shared_ptr<WebSocket> const&, std::string const& message, bool binary)> message;
         std::function<void(std::shared_ptr<WebSocket> const&)> close;
+        std::function<void(char const* reason)> stuck; // a stuck close (WebSocket)
         std::size_t maxMessage = 64 * 1024; // larger messages close the connection (1009)
     };
 
diff --git a/tests/integration/interact_test.py b/tests/integration/interact_test.py
index 6c2279e..8dd6a61 100644
--- a/tests/integration/interact_test.py
+++ b/tests/integration/interact_test.py
@@ -10,6 +10,7 @@
     interact_test.py [host:port] [container domain-dir]
 """
 import base64
+import hashlib
 import json
 import os
 import re
@@ -52,8 +53,9 @@ def ws_messages(sock, seconds):
     return ws_read(sock, seconds)[0]
 
 
-def ws_read(sock, seconds):
-    """Text messages and the number of binary frames (previews) received within `seconds`."""
+def ws_read(sock, seconds, pictures=None):
+    """Text messages and the number of binary frames (previews) received within `seconds`.
+    `pictures`, a list, gets the digest of each preview's JPEG (after the 8-byte grain)."""
     out, frames, buf = [], 0, _partial.pop(sock, b"")
     end = time.time() + seconds
     sock.settimeout(0.2)
@@ -82,6 +84,8 @@ def ws_read(sock, seconds):
                 out.append(json.loads(payload))
             elif opcode == 0x2:
                 frames += 1
+                if pictures is not None:
+                    pictures.append(hashlib.md5(payload[8:]).hexdigest())
     _partial[sock] = buf
     return out, frames
 
@@ -176,6 +180,27 @@ def fps(sock):
     b.close()
 
 
+def preview_new_pictures(host, port):
+    """SPEC §7.3: every preview frame of a moving page is a new picture (1.3.3 resent the previous
+    JPEG when the preview took longer than 20 ms: about 2 new pictures a second on a busy page)."""
+    page = ("data:text/html,<body style=margin:0><canvas id=c width=1920 height=1080></canvas><script>"
+            "const g=c.getContext('2d');let n=0;(function f(){g.fillStyle=`hsl(${n*7%360},70%,50%)`;"
+            "g.fillRect(0,0,1920,1080);g.fillStyle='%23fff';g.font='300px sans-serif';g.fillText(n++,200,600);"
+            "requestAnimationFrame(f)})()</script>")
+    request = urllib.request.Request(f"http://{host}:{port}/api/v1/source/navigate", method="POST",
+                                     data=json.dumps({"url": page}).encode(), headers={"Content-Type": "application/json"})
+    urllib.request.urlopen(request, timeout=5).read()
+    time.sleep(2)
+    sock = ws_connect(host, port, "/api/v1/interact")
+    ws_read(sock, 1)
+    pictures = []
+    frames = ws_read(sock, 4, pictures)[1]
+    repeats = sum(1 for a, b in zip(pictures, pictures[1:]) if a == b)
+    assert frames >= 30 and repeats == 0, f"{frames} frames, {repeats} repeated the previous picture"
+    print(f"OK: preview of a moving page: {frames} frames in 4 s, none repeats the previous picture")
+    sock.close()
+
+
 def metric(host, port, name):
     with urllib.request.urlopen(f"http://{host}:{port}/metrics", timeout=5) as response:
         text = response.read().decode()
@@ -200,7 +225,9 @@ def stuck_client(host, port, observer):
     assert rate >= 15, "the unread client slowed the controller"
     assert dropped > 0, "no preview frame dropped for the unread client"
     assert sessions == 1, "the unread client was not closed"
-    print("OK: an unread client does not slow the controller's preview and is closed")
+    stuck = metric(host, port, "websocket_stuck_closes_total")
+    assert stuck >= 1, "the stuck close was not counted"
+    print(f"OK: an unread client does not slow the controller's preview and is closed ({stuck:.0f} stuck close counted)")
     observer.close()
     c.close()
 
@@ -258,6 +285,7 @@ def main():
     control.close()
     stuck_client(host, port, observer)
     preview_rates(host, port)
+    preview_new_pictures(host, port)
 
 
 if __name__ == "__main__":
diff --git a/tests/integration/metrics_test.py b/tests/integration/metrics_test.py
index 8108e8e..3f108d6 100755
--- a/tests/integration/metrics_test.py
+++ b/tests/integration/metrics_test.py
@@ -13,6 +13,7 @@
     "page_hangs_total",
     "preview_frames_total",
     "preview_frames_dropped_total",
+    'websocket_stuck_closes_total{reason="outbox_age"}',
     "popups_blocked_total",
     "downloads_blocked_total",
     'renderer_crashes_total{reason="crashed"}',
diff --git a/tests/unit/test_counters.cpp b/tests/unit/test_counters.cpp
index c05ff4b..3454aa6 100644
--- a/tests/unit/test_counters.cpp
+++ b/tests/unit/test_counters.cpp
@@ -34,7 +34,7 @@ TEST_CASE("the event counters are on /metrics at 0 from the start")
     util::Metrics m("p_");
     ops::startCounters(m, true);
     auto const text = m.render();
-    for (auto const* line : {"p_page_hangs_total 0", "p_preview_frames_total 0", "p_preview_frames_dropped_total 0", "p_popups_blocked_total 0",
+    for (auto const* line : {"p_page_hangs_total 0", "p_preview_frames_total 0", "p_preview_frames_dropped_total 0", R"(p_websocket_stuck_closes_total{reason="outbox_age"} 0)", "p_popups_blocked_total 0",
              "p_downloads_blocked_total 0", R"(p_page_loads_total{result="error"} 0)", R"(p_renderer_crashes_total{reason="hung"} 0)",
              R"(p_renderer_crashes_total{reason="crashed"} 0)", R"(p_js_dialogs_total{type="alert"} 0)", R"(p_permission_denied_total{type="camera"} 0)",
              R"(p_navigation_blocked_total{reason="service_worker"} 0)", R"(p_console_messages_total{level="error"} 0)",
diff --git a/tests/unit/test_httpserver.cpp b/tests/unit/test_httpserver.cpp
index 66aa84b..79e090a 100644
--- a/tests/unit/test_httpserver.cpp
+++ b/tests/unit/test_httpserver.cpp
@@ -258,6 +258,7 @@ TEST_CASE("WebSocket: a client that stops reading never blocks a send; text stay
 {
     std::shared_ptr<WebSocket> socket;
     std::mutex mutex;
+    std::vector<std::string> stuckReasons; // reported stuck closes, in order
     HttpServer server([](HttpRequest const&, HttpResponse& res) { res.status = 404; },
         [&](HttpRequest const&, HttpResponse&) -> std::optional<WebSocketHandlers> {
             WebSocketHandlers h;
@@ -265,6 +266,10 @@ TEST_CASE("WebSocket: a client that stops reading never blocks a send; text stay
                 std::lock_guard lock{mutex};
                 socket = s;
             };
+            h.stuck = [&](char const* reason) {
+                std::lock_guard lock{mutex};
+                stuckReasons.emplace_back(reason);
+            };
             return h;
         });
     std::string error;
@@ -421,4 +426,14 @@ TEST_CASE("WebSocket: a client that stops reading never blocks a send; text stay
     CHECK(!bigWs->open());
     ::close(bigFd);
     server.stop();
+    // Each stuck close was reported once, with its reason (the first client recovered). The
+    // preview client's started frame waits in the outbox, so its age closes it.
+    std::lock_guard lock{mutex};
+    std::string reported;
+    for (auto const& r : stuckReasons)
+    {
+        reported += r + " ";
+    }
+    INFO(reported);
+    CHECK(stuckReasons == std::vector<std::string>{"outbox_age", "outbox_age", "outbox_size"});
 }

From da8aa1fd9365df2883cc8d9172adeda665268cda Mon Sep 17 00:00:00 2001
From: Adrian Hilber <LeeO86@users.noreply.github.com>
Date: Thu, 5 Nov 2026 03:26:31 +0100
Subject: [PATCH 2/5] interact_test: the second session keeps reading while the
 first is measured
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

With at most 64 KiB unsent in the kernel, a session that reads nothing is
closed after 5 s as SPEC §7.3 says; the test left one unread for ~8 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017ybuzgBaGxuB5UiaE8dRa4
---
 tests/integration/interact_test.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/tests/integration/interact_test.py b/tests/integration/interact_test.py
index 8dd6a61..f5206e5 100644
--- a/tests/integration/interact_test.py
+++ b/tests/integration/interact_test.py
@@ -18,6 +18,7 @@
 import struct
 import subprocess
 import sys
+import threading
 import time
 import urllib.request
 
@@ -158,8 +159,14 @@ def preview_rates(host, port):
     b = ws_connect(host, port, "/api/v1/interact")
 
     def fps(sock):
+        # The other session keeps reading: one that reads nothing for 5 s is closed (SPEC §7.3).
+        other = b if sock is a else a
+        drain = threading.Thread(target=ws_read, args=(other, 4))
+        drain.start()
         ws_read(sock, 1)  # frames still queued at the old rate
-        return ws_read(sock, 3)[1] / 3
+        rate = ws_read(sock, 3)[1] / 3
+        drain.join()
+        return rate
 
     watcher = fps(a)
     ws_send(a, {"type": "interact", "enable": True, "take": True})

From e1a15c3af2dd73671b84dfaff9aa8423183da288 Mon Sep 17 00:00:00 2001
From: Adrian Hilber <LeeO86@users.noreply.github.com>
Date: Thu, 5 Nov 2026 03:38:59 +0100
Subject: [PATCH 3/5] interact_test: animate the test page through execute
 (data: pages are refused)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017ybuzgBaGxuB5UiaE8dRa4
---
 tests/integration/interact_test.py | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/tests/integration/interact_test.py b/tests/integration/interact_test.py
index f5206e5..0037cac 100644
--- a/tests/integration/interact_test.py
+++ b/tests/integration/interact_test.py
@@ -190,12 +190,14 @@ def fps(sock):
 def preview_new_pictures(host, port):
     """SPEC §7.3: every preview frame of a moving page is a new picture (1.3.3 resent the previous
     JPEG when the preview took longer than 20 ms: about 2 new pictures a second on a busy page)."""
-    page = ("data:text/html,<body style=margin:0><canvas id=c width=1920 height=1080></canvas><script>"
-            "const g=c.getContext('2d');let n=0;(function f(){g.fillStyle=`hsl(${n*7%360},70%,50%)`;"
-            "g.fillRect(0,0,1920,1080);g.fillStyle='%23fff';g.font='300px sans-serif';g.fillText(n++,200,600);"
-            "requestAnimationFrame(f)})()</script>")
-    request = urllib.request.Request(f"http://{host}:{port}/api/v1/source/navigate", method="POST",
-                                     data=json.dumps({"url": page}).encode(), headers={"Content-Type": "application/json"})
+    # data: pages are refused by the URL policy: animate the test page instead.
+    animate = ("const c=document.createElement('canvas');c.width=1920;c.height=1080;"
+               "c.style='position:fixed;left:0;top:0;z-index:9';document.body.appendChild(c);"
+               "const g=c.getContext('2d');let n=0;(function f(){g.fillStyle=`hsl(${n*7%360},70%,50%)`;"
+               "g.fillRect(0,0,1920,1080);g.fillStyle='#fff';g.font='300px sans-serif';g.fillText(n++,200,600);"
+               "requestAnimationFrame(f)})()")
+    request = urllib.request.Request(f"http://{host}:{port}/api/v1/source/execute", method="POST",
+                                     data=json.dumps({"js": animate}).encode(), headers={"Content-Type": "application/json"})
     urllib.request.urlopen(request, timeout=5).read()
     time.sleep(2)
     sock = ws_connect(host, port, "/api/v1/interact")

From 4f3ba91987cc8dcb4182cd5bde6a75af75c5b51c Mon Sep 17 00:00:00 2001
From: Adrian Hilber <LeeO86@users.noreply.github.com>
Date: Thu, 5 Nov 2026 03:49:00 +0100
Subject: [PATCH 4/5] pages_test: read the control session's previews in the
 background

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017ybuzgBaGxuB5UiaE8dRa4
---
 tests/integration/interact_test.py | 16 ++++++++++++++++
 tests/integration/pages_test.py    |  3 ++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/tests/integration/interact_test.py b/tests/integration/interact_test.py
index 0037cac..823d9d2 100644
--- a/tests/integration/interact_test.py
+++ b/tests/integration/interact_test.py
@@ -49,6 +49,22 @@ def ws_send(sock, obj):
 _partial = {}  # socket -> bytes of a frame that had not fully arrived when ws_messages returned
 
 
+def drain(sock):
+    """Reads and discards everything `sock` receives, in the background: a session that reads
+    nothing for 5 s is closed as stuck (SPEC §7.3), also when its test only sends input."""
+    def run():
+        sock.settimeout(0.5)
+        while True:
+            try:
+                if not sock.recv(65536):
+                    return
+            except socket.timeout:
+                continue
+            except OSError:
+                return
+    threading.Thread(target=run, daemon=True).start()
+
+
 def ws_messages(sock, seconds):
     """Text messages received within `seconds` (binary frames are skipped)."""
     return ws_read(sock, seconds)[0]
diff --git a/tests/integration/pages_test.py b/tests/integration/pages_test.py
index abc53d6..9f9460a 100644
--- a/tests/integration/pages_test.py
+++ b/tests/integration/pages_test.py
@@ -9,7 +9,7 @@
 """
 import time
 
-from interact_test import ws_connect, ws_messages, ws_send
+from interact_test import drain, ws_connect, ws_messages, ws_send
 from ops_test import HOST, PORT, metric, navigate, status
 
 
@@ -113,6 +113,7 @@ def permissions(events, control):
     ws_send(control, {"type": "hello", "client": "pages_test", "protocol": 1})
     ws_send(control, {"type": "interact", "enable": True})
     ws_send(control, {"type": "focus", "focused": True})
+    drain(control)  # it only sends input; its previews must still be read
     dialogs(events, control)
     popup(events, control)
     download(events, control)

From bfabb866b8459307f39c029632da3dd06a0a2433 Mon Sep 17 00:00:00 2001
From: Adrian Hilber <LeeO86@users.noreply.github.com>
Date: Thu, 5 Nov 2026 03:49:13 +0100
Subject: [PATCH 5/5] CHANGELOG: a client of /api/v1/interact that reads
 nothing is closed after 5 s

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017ybuzgBaGxuB5UiaE8dRa4
---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ef7832..d9669cb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@
 - **Stuck closes are logged and counted** (SPEC §7.3, §12). A WebSocket closed because its client did not read (which ends interaction control) logs `websocket_stuck_close` with the client and reason and counts `websocket_stuck_closes_total{reason}` (`outbox_size`, `outbox_age`, `preview_not_taken`; at 0 from the start).
   - Tests: `tests/unit/test_httpserver.cpp` (each reason reported once), `tests/unit/test_counters.cpp`, `tests/integration/metrics_test.py`, `interact_test.py`.
 - **Previews do not pile up in the kernel** (SPEC §7.3). WebSockets keep at most 64 KiB unsent (`TCP_NOTSENT_LOWAT`); on a slow path the server drops previews early instead of holding seconds of them in the send buffer, so the preview latency no longer grows and shrinks.
+  - **Behaviour change for clients:** a client of `/api/v1/interact` must read what it receives. One that only sends input and reads nothing is now closed after about 5 s (before, the kernel buffered megabytes of previews, so it took much longer); the web UI and widget always read. Tests that drive input read in the background (`tests/integration/pages_test.py`).
 
 ## Image variant 1.3.3.2-codecs (2026-11-05)