From 6d15efdbf3756ee1b0d2feeb58945cf1fd7fb08a Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 10:36:02 -0500
Subject: [PATCH 01/10] fix(desktop): keep TextArea appends as appends once the
 byte bound is reached

Once a TextArea held `max_text_bytes` (16 KiB by default, the Log Viewer's
console), every further append replaced the pending TextAppend with a full
`Text` of the bounded text, because only the device applied the byte bound.
Each 200 ms Log Viewer pump then sent ~16.4 KB (five max-size frames) instead
of one ~400 B append; max-size frames need a fully drained 4096-byte USB FIFO
and the vendor write path polls once per tick (10 ms at 100 Hz), so writes
timed out, were dropped, the "host must resync" warnings fed back into the
captured log, and the desktop task stalled until the device was unplugged.

- the browser now applies the same byte bound (DESKTOP record MaxTextBytes)
  with the firmware's exact cut rule (cut = size - max, moved to the next
  line start when a newline follows, then past UTF-8 continuation bytes), in
  both console and edit modes, so an append stays a TextAppend on the wire;
  only a pending append larger than the whole bound still becomes a Text
- `boundTextBytes` in the pure block, codec-test vectors mirroring the host
  test, and a selftest case (line-start cut, mid-line cut with re-render)
- host test: an append past the bound stays an append; UTF-8 continuation
  cut; a pending append larger than the bound becomes a Text
- the example runs FreeRTOS at 1 kHz so a waiting USB write polls every
  1 ms instead of 10 ms

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/README.md                  |  8 ++-
 components/desktop/example/sdkconfig.defaults |  3 +
 components/desktop/include/desktop.hpp        |  3 +-
 .../desktop/include/detail/desktop_model.hpp  | 23 ++++---
 components/desktop/test/desktop_host_test.cpp | 35 +++++++++-
 components/desktop/web/desktop.html           | 64 ++++++++++++++++---
 .../desktop/web/test/desktop_codec_test.js    | 11 +++-
 7 files changed, 121 insertions(+), 26 deletions(-)

diff --git a/components/desktop/README.md b/components/desktop/README.md
index 443355b7da..3b7d3f6ec9 100644
--- a/components/desktop/README.md
+++ b/components/desktop/README.md
@@ -86,9 +86,11 @@ once.
   `Items` ranges accumulate (an `ItemCount` / full `set_items` discards earlier
   ranges), a removed widget cancels its pending changes, a window opened and
   closed between flushes sends nothing. A TextArea keeps its last `max_lines`
-  lines (the browser applies the same rule) and at most `max_text_bytes`; when
-  the byte bound trims, the host gets a full `Text` replacement so both sides
-  hold the same text. Per-window order: WINDOW_CLOSE ->
+  lines and at most `max_text_bytes` (advertised as `MaxTextBytes`); the
+  browser applies both bounds with the same rules to its copy, so an append
+  stays a `TextAppend` on the wire even when it trims (a log that has filled
+  its bound costs one append per flush, not the whole text). Per-window
+  order: WINDOW_CLOSE ->
   WINDOW_OPEN (full tree) -> WIDGET_ADD -> WIDGET_SET -> WIDGET_REMOVE; then
   DIALOG / DIALOG_CLOSE -> NOTIFY -> DESKTOP (when apps or settings changed).
 - The only frame sent from another context is `DesktopService`'s ERROR for a
diff --git a/components/desktop/example/sdkconfig.defaults b/components/desktop/example/sdkconfig.defaults
index 36f2498e04..4458e8575c 100644
--- a/components/desktop/example/sdkconfig.defaults
+++ b/components/desktop/example/sdkconfig.defaults
@@ -20,6 +20,9 @@ CONFIG_TINYUSB_CDC_TX_BUFSIZE=4096
 
 # Task statistics for MonitorService and the Task Manager app: the FreeRTOS
 # trace facility + run-time stats, and the core id per task.
+# 1 kHz tick: the USB write path polls the TX FIFO once per tick while a
+# frame waits for room, so a 100 Hz tick turns every wait into 10 ms steps
+CONFIG_FREERTOS_HZ=1000
 CONFIG_FREERTOS_USE_TRACE_FACILITY=y
 CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS=y
 CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID=y
diff --git a/components/desktop/include/desktop.hpp b/components/desktop/include/desktop.hpp
index 91d487087d..9b355a227e 100644
--- a/components/desktop/include/desktop.hpp
+++ b/components/desktop/include/desktop.hpp
@@ -179,7 +179,8 @@ class Desktop : public BaseComponent {
     /// queued commands are never evicted.
     size_t max_queued_commands{64};
     /// Bound on a TextArea's retained text and on a text the host sends for
-    /// one widget (Text events are reassembled up to this size).
+    /// one widget (Text events are reassembled up to this size). Advertised to
+    /// the host (DESKTOP record MaxTextBytes), which applies the same bound.
     size_t max_text_bytes{16 * 1024};
     /// The desktop task: every app callback runs on it, so size the stack for
     /// the apps (file I/O and fmt formatting comfortably fit 8 KiB).
diff --git a/components/desktop/include/detail/desktop_model.hpp b/components/desktop/include/detail/desktop_model.hpp
index 90fc97065a..f637c9edb4 100644
--- a/components/desktop/include/detail/desktop_model.hpp
+++ b/components/desktop/include/detail/desktop_model.hpp
@@ -825,19 +825,20 @@ class Model {
     return true;
   }
 
-  /// Append to a widget's text (TextArea: bounded by max_lines, which the host
-  /// applies identically, and max_text_bytes, which only the device applies:
-  /// when the latter trims, the host gets a full Text replacement instead of
-  /// the append so the two never diverge).
+  /// Append to a widget's text. A TextArea is bounded by max_lines and by
+  /// max_text_bytes (advertised as the DESKTOP record MaxTextBytes); the host
+  /// applies BOTH bounds with the same rules to its own copy, so an append
+  /// stays an append on the wire even when it trims (sending the whole bounded
+  /// text on every append past the bound would multiply the traffic by the
+  /// bound / append ratio and stall the link). Only a pending append larger
+  /// than the whole bound becomes a Text replacement (cheaper than the append).
   bool append_text(uint16_t win, uint16_t widget_id, std::string_view text) {
     WidgetState *s = this->widget(win, widget_id);
     if (!s)
       return false;
     s->text += text;
-    if (s->type == dp::WidgetType::TextArea && bound_text(*s)) {
-      dirty.set(win, widget_id, dp::Prop::text(dp::PropTag::Text, s->text));
-      return true;
-    }
+    if (s->type == dp::WidgetType::TextArea)
+      bound_text(*s);
     const size_t pending = dirty.set(win, widget_id, dp::Prop::text(dp::PropTag::TextAppend, text));
     if (pending > max_text_bytes) {
       // the host would receive more than it keeps: replace with the bounded text
@@ -1164,8 +1165,10 @@ class Model {
 
   /// Keep a TextArea's text to its last max_lines lines (the same rule as the
   /// browser's ring: the text after the last newline counts as a line, so
-  /// "a\nb\n" is three lines) and to max_text_bytes bytes. Returns true when
-  /// the BYTE bound cut something (the host does not apply it).
+  /// "a\nb\n" is three lines) and to max_text_bytes bytes (the browser applies
+  /// this exact byte rule too: cut = size - max, moved to the start of the next
+  /// line when one follows, then past any UTF-8 continuation bytes). Returns
+  /// true when the BYTE bound cut something.
   bool bound_text(WidgetState &s) const {
     if (s.max_lines) {
       const size_t lines = static_cast<size_t>(std::count(s.text.begin(), s.text.end(), '\n')) + 1;
diff --git a/components/desktop/test/desktop_host_test.cpp b/components/desktop/test/desktop_host_test.cpp
index 3382772687..027dd93b08 100644
--- a/components/desktop/test/desktop_host_test.cpp
+++ b/components/desktop/test/desktop_host_test.cpp
@@ -1479,10 +1479,41 @@ static void test_model_flush() {
   CHECK(s && s->entries.size() == 1 && s->entries[0].props.size() == 1 &&
         s->entries[0].props[0].is(PropTag::TextAppend) &&
         s->entries[0].props[0].as_text() == "line0\nline1\nline2\nline3\nline4\n");
+  // an append that pushes the stored text past the BYTE bound stays an append
+  // on the wire (the host applies the same bound to its copy); the retained
+  // text is cut at the start of the line that straddles the bound
+  {
+    m.max_text_bytes = 24;
+    m.set_prop(win, ta, Prop::text(PropTag::Text, "0123456789\nabcdefghij\n")); // 22 B
+    m.flush();
+    m.append_text(win, ta, "KLMNO\n"); // 28 B > 24: cut to the next line start
+    CHECK(m.widget(win, ta)->text == "abcdefghij\nKLMNO\n");
+    out = m.flush();
+    s = out.size() == 1 ? decode_widget_set(out[0].payload) : std::nullopt;
+    CHECK(s && s->entries.size() == 1 && s->entries[0].props.size() == 1 &&
+          s->entries[0].props[0].is(PropTag::TextAppend) &&
+          s->entries[0].props[0].as_text() == "KLMNO\n");
+    // a cut with no newline after it lands mid-line, past a UTF-8 continuation byte
+    m.set_prop(win, ta,
+               Prop::text(PropTag::Text, "a\xc3\xa9"
+                                         "bcdefghijklmnopqrs")); // 21 B
+    m.flush();
+    m.append_text(win, ta, "uvwxy"); // 26 B: cut = 2 is the continuation byte of U+00E9
+    CHECK(m.widget(win, ta)->text == "bcdefghijklmnopqrsuvwxy" &&
+          m.widget(win, ta)->text.size() == 23);
+    out = m.flush();
+    s = out.size() == 1 ? decode_widget_set(out[0].payload) : std::nullopt;
+    CHECK(s && s->entries.size() == 1 && s->entries[0].props.size() == 1 &&
+          s->entries[0].props[0].is(PropTag::TextAppend) &&
+          s->entries[0].props[0].as_text() == "uvwxy");
+    m.max_text_bytes = 64;
+    m.set_prop(win, ta, Prop::text(PropTag::Text, ""));
+    m.flush();
+  }
   m.append_text(win, ta, std::string(100, 'x'));
   CHECK(m.widget(win, ta)->text.size() <= 64);
-  // the pending append grew past max_text_bytes: it became a Text (replace)
-  // of the bounded text, cancelling the append
+  // a pending append LARGER than max_text_bytes is replaced by a Text of the
+  // bounded text (never more than max_text_bytes on the wire), cancelling the append
   out = m.flush();
   s = out.size() == 1 ? decode_widget_set(out[0].payload) : std::nullopt;
   CHECK(s && s->entries.size() == 1 && s->entries[0].props.size() == 1 &&
diff --git a/components/desktop/web/desktop.html b/components/desktop/web/desktop.html
index 7d1829269e..351660756f 100644
--- a/components/desktop/web/desktop.html
+++ b/components/desktop/web/desktop.html
@@ -1009,6 +1009,21 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
       while (n > 0 && (b[n] & 0xC0) === 0x80) n--;
       return utf8Decoder.decode(b.subarray(0, n));
     }
+    // The device's byte bound on a TextArea (DESKTOP record MaxTextBytes), with
+    // the firmware's exact rule so both copies stay identical: when the UTF-8
+    // size exceeds `maxBytes`, cut = size - maxBytes, moved to the start of the
+    // next line when a newline follows the cut (and is not the last byte), then
+    // past any UTF-8 continuation bytes. Returns the (possibly unchanged) text.
+    function boundTextBytes(text, maxBytes) {
+      const str = String(text == null ? "" : text);
+      const b = utf8Encoder.encode(str);
+      if (!(maxBytes > 0) || b.length <= maxBytes) return str;
+      let cut = b.length - maxBytes;
+      const nl = b.indexOf(0x0A, cut);
+      if (nl !== -1 && nl + 1 < b.length) cut = nl + 1;
+      while (cut < b.length && (b[cut] & 0xC0) === 0x80) cut++;
+      return utf8Decoder.decode(b.subarray(cut));
+    }
     // Split UTF-8 text into Text-event chunks that fit `maxPayload` (never
     // cutting a UTF-8 sequence in half); an empty text is one empty chunk.
     function chunkText(bytes, maxPayload) {
@@ -3054,10 +3069,22 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
           };
           wd.trim = () => {
             const max = wd.st.maxLines;
-            if (!max) return;
-            while (wd.st.lines.length > max) {
-              wd.st.lines.shift();
-              if (wd.st.mode === "console" && wd.inner.firstChild) wd.inner.removeChild(wd.inner.firstChild);
+            if (max) {
+              while (wd.st.lines.length > max) {
+                wd.st.lines.shift();
+                if (wd.st.mode === "console" && wd.inner.firstChild) wd.inner.removeChild(wd.inner.firstChild);
+              }
+            }
+            // the device keeps at most MaxTextBytes and applies this same rule
+            // to ITS copy on every append, so appends stay appends on the wire
+            const raw = wd.st.lines.map((l) => l.raw).join("\n");
+            const bounded = boundTextBytes(raw, settings.maxTextBytes);
+            if (bounded !== raw) {
+              const kept = bounded.split("\n");
+              const drop = wd.st.lines.length - kept.length;
+              for (let i = 0; i < drop; i++) { wd.st.lines.shift(); if (wd.st.mode === "console" && wd.inner.firstChild) wd.inner.removeChild(wd.inner.firstChild); }
+              if (wd.st.lines.length && wd.st.lines[0].raw !== kept[0]) { wd.st.lines[0].raw = kept[0]; if (wd.st.mode === "console") wd.renderLine(0); }
+              if (wd.st.mode === "edit" && wd.inner.value !== bounded) wd.inner.value = bounded;
             }
             if (wd.st.lines.length) wd.st.lines[0].startState = null;
           };
@@ -3073,15 +3100,15 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
               wd.st.lines.push({ raw: parts[i], startState });
               if (wd.st.mode === "console") { const node = document.createElement("div"); node.className = "line"; wd.inner.appendChild(node); wd.renderLine(wd.st.lines.length - 1); }
             }
-            wd.trim();
             if (wd.st.mode === "edit") { wd.inner.value += text; wd.st.dirty = false; }
-            else if (stick) wd.inner.scrollTop = wd.inner.scrollHeight;
+            wd.trim(); // the line bound, then the device's byte bound (edit mode: inner.value follows)
+            if (wd.st.mode === "console" && stick) wd.inner.scrollTop = wd.inner.scrollHeight;
           };
           wd.setText = (text) => {
             wd.st.lines = String(text).split("\n").map((raw) => ({ raw, startState: null }));
-            wd.trim();
-            if (wd.st.mode === "edit") { wd.inner.value = text; wd.st.dirty = false; }
-            else wd.renderAll();
+            if (wd.st.mode === "edit") { wd.inner.value = String(text); wd.st.dirty = false; }
+            wd.trim(); // line bound, then the device's byte bound (edit mode: inner.value follows)
+            if (wd.st.mode === "console") wd.renderAll();
           };
           wd.dispose = () => idle.cancel();
           wd.setMode("edit");
@@ -3626,6 +3653,25 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
       ta.value = "z".repeat(settings.maxTextBytes + 10); ta.dispatchEvent(new Event("input", { bubbles: true }));
       assert(ta.value.length === settings.maxTextBytes && ta.classList.contains("overflow"), "TextArea edit capped at MaxTextBytes");
       w.widgets.get(4).idle.flush(); await txQueue; await tick(0); // drain the capped edit's Text chunks
+      // 8b. a console TextArea applies the device's byte bound (MaxTextBytes) on
+      // appends with the firmware's cut rule, so appends can stay appends
+      {
+        feedHex(DT.WIDGET_ADD, "0100" + "0100" + "6000" + "0000" + "08" + "01" + "01" + "02" + "10" + "0200" + "0100" + "11" + "0200" + "0000"); // ReadOnly console, MaxLines 0
+        const cw = w.widgets.get(0x60);
+        assert(cw && cw.st.mode === "console", "console textarea added");
+        const saved = settings.maxTextBytes; settings.maxTextBytes = 24;
+        const app = (str) => { const b = utf8Encoder.encode(str); feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "02" + hexOf(new Uint8Array([b.length & 0xFF, b.length >> 8])) + hexOf(b)); };
+        app("0123456789\n"); app("abcdefghij\n"); app("KLMNO\n");
+        const rawOf = () => cw.st.lines.map((l) => l.raw).join("\n");
+        assert(rawOf() === "abcdefghij\nKLMNO\n" && cw.inner.children.length === 3, "byte bound cut at the next line start: " + JSON.stringify(rawOf()));
+        app("\u00e9\u00e9\u00e9\u00e9\u00e9"); // 10 B, pushes to 27 B: cut moves to the next line start again
+        assert(rawOf() === "KLMNO\n\u00e9\u00e9\u00e9\u00e9\u00e9" && cw.inner.children.length === 2, "byte bound keeps the device's exact tail: " + JSON.stringify(rawOf()));
+        app("abcdefghijklmnopqrstuvwxyz"); // 26 B on the last line: no newline after the cut, so it lands mid-line
+        assert(rawOf() === "cdefghijklmnopqrstuvwxyz" && cw.inner.children.length === 1, "mid-line cut drops the earlier lines and shortens the first: " + JSON.stringify(rawOf()));
+        assert(cw.inner.children[0].textContent === "cdefghijklmnopqrstuvwxyz", "first line re-rendered after a mid-line cut");
+        settings.maxTextBytes = saved;
+        feedHex(DT.WIDGET_REMOVE, "0100" + "0100" + "6000");
+      }
       // 9. a List added on the fly: Select / Activate
       feedHex(DT.WIDGET_ADD, "0100" + "0100" + "0700" + "0100" + "09" + "00" + "00" + "01" + "0c" + "0a00" + "0000" + "0200" + "0100" + "61" + "0100" + "62");
       const list = w.widgets.get(7);
diff --git a/components/desktop/web/test/desktop_codec_test.js b/components/desktop/web/test/desktop_codec_test.js
index 18255585c9..008efa5411 100644
--- a/components/desktop/web/test/desktop_codec_test.js
+++ b/components/desktop/web/test/desktop_codec_test.js
@@ -22,7 +22,7 @@ const end = html.indexOf("// ==== DESKTOP:END-PURE ====");
 assert(begin > 0 && end > begin, "pure-block markers not found in desktop.html");
 const pure = html.slice(begin, end);
 const P = new Function(pure + `
-  return { pickAutoConnectCandidate, sortedOrder, compareCells, cellSortKey, DT, DT_NAME, PROP, WT, WIN, WEV, WGEV, KEY, MOD, LAYOUT, TA_FLAG, MIN_WINDOW, DESKTOP_MAX_PAYLOAD_CAP, COLOR_DEFAULT, DESKTOP_HAS_SNAPSHOT, DESKTOP_WINDOW_LIST_COMPLETE, MAX_TEXT_BYTES_DEFAULT, SUBMIT_EVENT_HEADER, DIALOG_RESULT_HEADER, utf8ByteLength, truncateUtf8,
+  return { boundTextBytes, pickAutoConnectCandidate, sortedOrder, compareCells, cellSortKey, DT, DT_NAME, PROP, WT, WIN, WEV, WGEV, KEY, MOD, LAYOUT, TA_FLAG, MIN_WINDOW, DESKTOP_MAX_PAYLOAD_CAP, COLOR_DEFAULT, DESKTOP_HAS_SNAPSHOT, DESKTOP_WINDOW_LIST_COMPLETE, MAX_TEXT_BYTES_DEFAULT, SUBMIT_EVENT_HEADER, DIALOG_RESULT_HEADER, utf8ByteLength, truncateUtf8,
            ByteReader, ByteWriter, hexOf, bytesOfHex, propKind, readRec, decodeProp, propBytes, desktopSettings,
            decodeMessage, encodeMessage, decodeWidgetSet, decodeDesktop, chunkText, keyCodeFor,
            clampGeometry, geometryEquals, resizeGeometry, placeWindow, createGeometryStore, geometryKey,
@@ -332,6 +332,15 @@ test("registry metadata and wiring constants", () => {
     assert.strictEqual(P.pickAutoConnectCandidate([other], [port(0x2341), { getInfo: () => { throw new Error("x"); } }], 0x1209), null);
     assert.strictEqual(P.pickAutoConnectCandidate(null, undefined, 0x1209), null);
   }
+  // the device's byte bound on a TextArea: the firmware's exact cut rule (desktop_model.hpp bound_text)
+  {
+    assert.strictEqual(P.boundTextBytes("abc", 24), "abc");
+    assert.strictEqual(P.boundTextBytes("0123456789\nabcdefghij\nKLMNO\n", 24), "abcdefghij\nKLMNO\n", "cut moves to the next line start");
+    assert.strictEqual(P.boundTextBytes("ab\u00e9cdefghijklmnopqrstuvwxyz", 24), "cdefghijklmnopqrstuvwxyz", "no newline: mid-line cut past the UTF-8 continuation byte");
+    assert.strictEqual(P.boundTextBytes("0123456789\n", 4), "789\n", "a newline that is the LAST byte does not move the cut");
+    assert.strictEqual(P.boundTextBytes("abc", 0), "abc", "a zero bound is ignored");
+    assert.strictEqual(P.boundTextBytes(null, 8), "");
+  }
   assert.strictEqual(P.MIN_WINDOW.w, 160);
 });
 test("the pure block touches no DOM, window, storage or timers", () => {

From 26fe30b83997678eea371bd4acbd49c6637b7e52 Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 10:42:46 -0500
Subject: [PATCH 02/10] fix(desktop): keep ANSI state across a mid-line trim;
 edit mode follows MaxLines trims

Review round 1:
- a mid-line byte cut now renders the kept suffix from the ANSI state the
  removed prefix left behind (ansiSplit over the prefix), and the first
  line's startState is no longer reset to null after a trim: surviving
  console nodes were rendered from the state the removed text really
  produced, so they stay valid without a full re-render
- edit mode: the <textarea> follows the device's copy after EITHER bound
  (a MaxLines trim used to shorten the lines but not the value), unless the
  user is mid-edit (dirty), whose text is sent whole and bounded + echoed
  by the device
- selftest: ANSI mid-line cut keeps the colour, edit-mode MaxLines trim
  syncs the value, a pending edit survives a MaxLines trim

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/web/desktop.html | 35 +++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/components/desktop/web/desktop.html b/components/desktop/web/desktop.html
index 351660756f..61f4ea450c 100644
--- a/components/desktop/web/desktop.html
+++ b/components/desktop/web/desktop.html
@@ -3076,17 +3076,28 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
               }
             }
             // the device keeps at most MaxTextBytes and applies this same rule
-            // to ITS copy on every append, so appends stay appends on the wire
+            // to ITS copy on every append, so appends stay appends on the wire.
+            // Dropping leading lines leaves the surviving console nodes valid:
+            // each line was rendered from the ANSI state the removed text really
+            // produced, and that state stays on the line (`startState`).
             const raw = wd.st.lines.map((l) => l.raw).join("\n");
             const bounded = boundTextBytes(raw, settings.maxTextBytes);
             if (bounded !== raw) {
               const kept = bounded.split("\n");
               const drop = wd.st.lines.length - kept.length;
               for (let i = 0; i < drop; i++) { wd.st.lines.shift(); if (wd.st.mode === "console" && wd.inner.firstChild) wd.inner.removeChild(wd.inner.firstChild); }
-              if (wd.st.lines.length && wd.st.lines[0].raw !== kept[0]) { wd.st.lines[0].raw = kept[0]; if (wd.st.mode === "console") wd.renderLine(0); }
-              if (wd.st.mode === "edit" && wd.inner.value !== bounded) wd.inner.value = bounded;
+              const first = wd.st.lines[0];
+              if (first && first.raw !== kept[0]) {
+                // a mid-line cut: the kept suffix starts in the ANSI state the removed prefix left behind
+                if (wd.st.flags & TA_FLAG.ANSI) first.startState = ansiSplit(first.raw.slice(0, first.raw.length - kept[0].length), first.startState).state;
+                first.raw = kept[0];
+                if (wd.st.mode === "console") wd.renderLine(0);
+              }
             }
-            if (wd.st.lines.length) wd.st.lines[0].startState = null;
+            // edit mode: the <textarea> follows the device's copy after either
+            // bound, unless the user is mid-edit (their text is sent whole and
+            // the device bounds + echoes it)
+            if (wd.st.mode === "edit" && !wd.st.dirty) { const v = wd.st.lines.map((l) => l.raw).join("\n"); if (wd.inner.value !== v) wd.inner.value = v; }
           };
           wd.append = (text) => {
             const parts = String(text).split("\n");
@@ -3669,7 +3680,23 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
         app("abcdefghijklmnopqrstuvwxyz"); // 26 B on the last line: no newline after the cut, so it lands mid-line
         assert(rawOf() === "cdefghijklmnopqrstuvwxyz" && cw.inner.children.length === 1, "mid-line cut drops the earlier lines and shortens the first: " + JSON.stringify(rawOf()));
         assert(cw.inner.children[0].textContent === "cdefghijklmnopqrstuvwxyz", "first line re-rendered after a mid-line cut");
+        // an ANSI console: a mid-line cut keeps the colour the removed prefix switched on
+        feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "10" + "0200" + "1100"); // Flags: ReadOnly | Ansi
+        feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "01" + "0000"); // Text ""
+        app("\x1b[31mred " + "0123456789abcdefghijklmnopqrstuvwxyz"); // 5 + 4 + 36 B: cut lands after the SGR code
+        assert(rawOf() === "cdefghijklmnopqrstuvwxyz" && cw.inner.children.length === 1, "ANSI mid-line cut: " + JSON.stringify(rawOf()));
+        assert(cw.inner.children[0].firstElementChild && cw.inner.children[0].firstElementChild.classList.contains("ansi-fg-1") && cw.inner.children[0].textContent === "cdefghijklmnopqrstuvwxyz", "the kept suffix is rendered in the colour the cut-off prefix selected");
+        // edit mode follows the device's copy after a MaxLines trim too, unless the user is mid-edit
+        feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "10" + "0200" + "0000"); // Flags 0 -> editable
+        assert(cw.st.mode === "edit", "textarea switched to edit mode");
         settings.maxTextBytes = saved;
+        feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "01" + "0a00" + hexOf(utf8Encoder.encode("a\nb\nc\nd\ne\n"))); // Text, 6 lines
+        feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "11" + "0200" + "0300"); // MaxLines 3
+        assert(cw.inner.value === "d\ne\n" && cw.st.lines.length === 3, "edit-mode textarea trimmed with the lines: " + JSON.stringify(cw.inner.value));
+        cw.inner.value = "d\ne\nedit"; cw.st.dirty = true;
+        feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "11" + "0200" + "0200"); // MaxLines 2
+        assert(cw.inner.value === "d\ne\nedit" && cw.st.lines.length === 2, "a pending edit is not discarded by a MaxLines trim");
+        cw.st.dirty = false; cw.idle.cancel();
         feedHex(DT.WIDGET_REMOVE, "0100" + "0100" + "6000");
       }
       // 9. a List added on the fly: Select / Activate

From 6e76054dbe5843ff8ffed16f226eeb2595fbdbb9 Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 13:59:48 -0500
Subject: [PATCH 03/10] fix(desktop): pause streaming to a sink that dropped a
 frame and re-snapshot it; packet-aligned WebUSB reads

Found with the board: once the console held more than 16 KiB the browser
died with "transport lost" even on the fixed firmware, and the log filled
with "Vendor TX FIFO full, dropping a 126-byte frame" at 4 lines/s.

1. Browser read length. desktop.html asked transferIn() for MAX_FRAME
   (4111 B). A bulk transfer ends on a short packet or a full buffer, so
   when the device streams several max-size frames back-to-back (the
   WINDOW_OPEN snapshot of a 16 KiB log, a busy Log Viewer) every packet is
   full and the one straddling byte 4111 overruns the buffer: the OS reports
   an overflow ("babble") and the pipe then errors out on every read
   (libusb: Overflow, then Pipe error; the page: "USB read error" ->
   transport lost). Reads are now 16 KiB rounded to the IN endpoint's packet
   size. Reproduced with a pyusb probe: 4111-byte reads fail on the first
   snapshot, 8192-byte reads move 1.3 MB in 26 s with 0 errors.

2. Device-initiated resync. When a host went away (page closed / reloaded)
   its sink stayed active: every flush blocked the desktop task for the
   transport's 250 ms drain timeout per frame, and UsbDevice's warning was
   appended to the Log Viewer, which produced the next frame to drop. Now
   send() stops at the first refused frame, the sink is paused (inactive +
   needs_resync) and the desktop re-sends the full snapshot by itself
   (unsolicited DESKTOP with the complete window list, then the snapshot
   WINDOW_OPENs -- which the browser already treats as authoritative) once
   the transport takes frames again, retrying every 1 s with back-off to
   8 s; a GET_DESKTOP resyncs immediately as before. detach() clears a
   pending resync (no host to heal while unplugged).

Docs: send_fn / needs_resync() / README flow-control paragraph.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/README.md                  |  15 +-
 components/desktop/include/desktop.hpp        | 145 ++++++++++++++----
 .../desktop/include/desktop_service.hpp       |  12 +-
 components/desktop/web/desktop.html           |  13 +-
 4 files changed, 147 insertions(+), 38 deletions(-)

diff --git a/components/desktop/README.md b/components/desktop/README.md
index 3b7d3f6ec9..0b1d67c7cd 100644
--- a/components/desktop/README.md
+++ b/components/desktop/README.md
@@ -172,10 +172,17 @@ it), then the descriptions (logged). Unregistering an app closes its windows
 (WINDOW_CLOSE reason 2) and its id is not reused while a window references it.
 
 Flow control: a `DesktopService::Config::send` returns whether the frame was
-queued (all-or-nothing); when it was not, the desktop logs and flags that
-transport (`needs_resync()`) until the host's next GET_DESKTOP. A full
-command queue (`Config::max_queued_commands`) refuses a request with
-ERROR(EAGAIN) and drops an event; nothing queued is evicted.
+queued (all-or-nothing). When it was not (the host went away or stopped
+reading), the desktop logs once, drops the rest of that batch, and PAUSES
+streaming to that transport (`needs_resync()`): every further write would
+only block the desktop task for the transport's drain timeout, and the
+host's mirror is incomplete anyway. It then re-sends the full snapshot by
+itself (an unsolicited DESKTOP with the complete window list, then one
+snapshot WINDOW_OPEN per window) once the transport takes frames again,
+retrying every 1 s and backing off to 8 s (`kResyncRetryMin/Max`; each attempt
+costs one failed write), or at the host's next GET_DESKTOP, whichever comes
+first. A full command queue (`Config::max_queued_commands`) refuses a request
+with ERROR(EAGAIN) and drops an event; nothing queued is evicted.
 
 ## Log capture
 
diff --git a/components/desktop/include/desktop.hpp b/components/desktop/include/desktop.hpp
index 9b355a227e..f2d8e69761 100644
--- a/components/desktop/include/desktop.hpp
+++ b/components/desktop/include/desktop.hpp
@@ -98,10 +98,14 @@ class Desktop : public BaseComponent {
   using window_event_fn = std::function<void(const WindowEvent &)>;
   /// Transmits one encoded frame to a host (one per transport; see add_sink).
   /// Returns false when the frame could NOT be queued (the transport is
-  /// gone, or its FIFO did not drain in time): the desktop then flags the
-  /// sink as needing a resync (sink_needs_resync) and logs, since the host's
-  /// mirror of the desktop is now incomplete until its next GET_DESKTOP. A
-  /// transport must never queue a partial frame (write a frame all-or-nothing).
+  /// gone, or its FIFO did not drain in time). The desktop then stops
+  /// streaming to that sink (its host's mirror is incomplete, and every
+  /// further write would block the desktop task for the transport's drain
+  /// timeout), flags it (sink_needs_resync) and re-sends the full snapshot by
+  /// itself once the transport takes frames again (retried with back-off,
+  /// kResyncRetryMin..kResyncRetryMax) -- or at the host's next GET_DESKTOP,
+  /// whichever comes first. A transport must never queue a partial frame
+  /// (write a frame all-or-nothing).
   using send_fn = std::function<bool(std::span<const uint8_t> frame)>;
 
   // Window flags (WindowConfig::flags / Window::set_flags).
@@ -153,6 +157,12 @@ class Desktop : public BaseComponent {
   static constexpr size_t kMaxFirmwareBytes = detail::dp::kMaxFirmwareBytes;
 
   /// Configuration for the Desktop.
+  /// Retry period of the device-initiated resync after a dropped frame (see
+  /// send_fn): starts at the minimum and doubles up to the maximum while the
+  /// transport keeps refusing frames (each attempt costs one failed write).
+  static constexpr std::chrono::milliseconds kResyncRetryMin{1000};
+  static constexpr std::chrono::milliseconds kResyncRetryMax{8000};
+
   struct Config {
     /// Shown in the browser's tray / title (at most kMaxDeviceNameBytes, else truncated).
     std::string device_name{"espp"};
@@ -936,8 +946,12 @@ class Desktop : public BaseComponent {
   ///        transport should be deactivated; the next GET_DESKTOP reactivates it).
   void set_sink_active(SinkId id, bool active) {
     std::lock_guard<std::recursive_mutex> lock(mutex_);
-    if (auto s = find_sink(id))
+    if (auto s = find_sink(id)) {
       s->active = active;
+      if (!active)
+        s->needs_resync.store(
+            false); // detached: no host to resync (the next GET_DESKTOP re-attaches)
+    }
     if (!active)
       text_.forget_sink(id); // a half-received text of the old session is garbage
   }
@@ -982,8 +996,9 @@ class Desktop : public BaseComponent {
     send(reject_sink, out);
   }
 
-  /// @brief Whether a frame to this sink was dropped since its last
-  ///        GET_DESKTOP (the host's mirror is incomplete until it resyncs).
+  /// @brief Whether a frame to this sink was dropped and the host's mirror is
+  ///        still incomplete: streaming to it is paused until the desktop's
+  ///        own snapshot gets through or the host sends GET_DESKTOP.
   bool sink_needs_resync(SinkId id) const {
     std::lock_guard<std::recursive_mutex> lock(mutex_);
     auto s = find_sink(id);
@@ -1130,7 +1145,11 @@ class Desktop : public BaseComponent {
     send_fn send{nullptr};
     std::mutex mutex; ///< held across `send` so this sink's frames never interleave
     bool active{false};
-    std::atomic<bool> needs_resync{false}; ///< a frame was dropped since the last GET_DESKTOP
+    /// A frame was dropped and no snapshot got through since: the sink is
+    /// inactive and resync_if_due() re-sends the snapshot at `resync_due`.
+    std::atomic<bool> needs_resync{false};
+    std::chrono::steady_clock::time_point resync_due{}; ///< guarded by mutex_
+    std::chrono::milliseconds resync_retry{0};          ///< current back-off, guarded by mutex_
   };
 
   /// The wire type of a command's request (for an ERROR reply).
@@ -1223,7 +1242,8 @@ class Desktop : public BaseComponent {
     }
     run_pending();
     flush_if_due();
-    // wait for the next due time (timer, flush) or a wake-up
+    resync_if_due();
+    // wait for the next due time (timer, flush, resync) or a wake-up
     std::chrono::steady_clock::time_point next = std::chrono::steady_clock::time_point::max();
     {
       std::lock_guard<std::recursive_mutex> lock(mutex_);
@@ -1237,6 +1257,9 @@ class Desktop : public BaseComponent {
                                   ->due);
       if (model_.dirty.any())
         next = std::min(next, last_flush_ + config_.flush_period);
+      for (const auto &s : sinks_)
+        if (s->needs_resync.load() && !s->active)
+          next = std::min(next, s->resync_due);
     }
     std::unique_lock<std::mutex> lock(m);
     if (next == std::chrono::steady_clock::time_point::max())
@@ -1288,7 +1311,6 @@ class Desktop : public BaseComponent {
     // to the requesting one (which becomes active)
     flush_now();
     std::shared_ptr<Sink> sink;
-    std::vector<OutMsg> out{};
     {
       std::lock_guard<std::recursive_mutex> lock(mutex_);
       sink = find_sink(cmd.sink);
@@ -1296,12 +1318,26 @@ class Desktop : public BaseComponent {
         return;
       sink->active = true;
       sink->needs_resync.store(false); // this reply is the resync
+    }
+    const size_t frames = send_snapshot(sink, cmd.correlation);
+    logger_.debug("GET_DESKTOP from sink {}: {} frames", cmd.sink, frames);
+  }
+
+  /// Encode the full state (DESKTOP, then one WINDOW_OPEN snapshot per window
+  /// and the open dialogs) under the lock and send it to one sink outside it:
+  /// the GET_DESKTOP reply (`correlation` echoed on the DESKTOP frame) or a
+  /// device-initiated resync (no correlation). Returns the number of frames
+  /// built (whether they were all taken is tracked by send()).
+  size_t send_snapshot(const std::shared_ptr<Sink> &sink, std::optional<uint16_t> correlation) {
+    std::vector<OutMsg> out{};
+    {
+      std::lock_guard<std::recursive_mutex> lock(mutex_);
       const bool has_snapshot = !model_.windows().empty() || !model_.dialogs().empty();
       bool trimmed = false;
       out.push_back({.type = detail::dp::Type::Desktop,
                      .payload = detail::dp::encode_desktop(model_.desktop_info(has_snapshot),
                                                            max_payload(), &trimmed),
-                     .correlation = cmd.correlation});
+                     .correlation = correlation});
       if (trimmed)
         logger_.warn("DESKTOP record set trimmed to fit {} bytes", max_payload());
       size_t dropped = 0;
@@ -1311,7 +1347,51 @@ class Desktop : public BaseComponent {
         logger_.warn("snapshot: {} oversized properties dropped", dropped);
     }
     send(sink, out);
-    logger_.debug("GET_DESKTOP from sink {}: {} frames", cmd.sink, out.size());
+    return out.size();
+  }
+
+  /// Device-initiated resync: a sink that dropped a frame (inactive since) is
+  /// sent the full snapshot again once its retry time comes. While the
+  /// transport still refuses frames each attempt costs one failed write and
+  /// the retry backs off; once the whole snapshot is taken the sink is active
+  /// again and the following flushes stream deltas to it. The browser treats
+  /// an unsolicited DESKTOP (complete window list) + snapshot WINDOW_OPENs as
+  /// authoritative, so this heals its mirror without a request.
+  void resync_if_due() {
+    std::vector<std::shared_ptr<Sink>> due{};
+    {
+      std::lock_guard<std::recursive_mutex> lock(mutex_);
+      const auto now = std::chrono::steady_clock::now();
+      std::copy_if(sinks_.begin(), sinks_.end(), std::back_inserter(due),
+                   [now](const std::shared_ptr<Sink> &s) {
+                     return s->needs_resync.load() && !s->active && now >= s->resync_due;
+                   });
+    }
+    for (const auto &sink : due) {
+      send_snapshot(sink, std::nullopt);
+      std::lock_guard<std::recursive_mutex> lock(mutex_);
+      if (sink->needs_resync.load())
+        continue; // a frame failed again: on_send_failed() re-armed the retry
+      sink->active = true;
+      logger_.info("sink {} took the snapshot again; streaming to it resumed", sink->id);
+    }
+  }
+
+  /// A sink's transport dropped a frame: stop streaming to it and schedule the
+  /// device-initiated resync (see send_fn). Called by send() after it released
+  /// the sink's mutex (this takes mutex_; the two are never held together).
+  void on_send_failed(const std::shared_ptr<Sink> &sink, size_t frame_bytes) {
+    std::lock_guard<std::recursive_mutex> lock(mutex_);
+    sink->active = false;
+    if (!sink->needs_resync.exchange(true)) {
+      sink->resync_retry = kResyncRetryMin;
+      logger_.warn("sink {} could not take a {}-byte frame; streaming to it is paused until it "
+                   "takes a snapshot again (retried every {} ms+) or the host sends GET_DESKTOP",
+                   sink->id, frame_bytes, kResyncRetryMin.count());
+    } else {
+      sink->resync_retry = std::min(sink->resync_retry * 2, kResyncRetryMax);
+    }
+    sink->resync_due = std::chrono::steady_clock::now() + sink->resync_retry;
   }
 
   void handle(const Command &cmd, const detail::dp::LaunchApp &req) {
@@ -1501,25 +1581,34 @@ class Desktop : public BaseComponent {
 
   /// Build the frames for one sink (with its module id) and transmit them,
   /// serialized on the sink's mutex (held across the callback). Never called
-  /// with mutex_ held.
-  void send(const std::shared_ptr<Sink> &sink, const std::vector<OutMsg> &out) {
+  /// with mutex_ held. Stops at the first frame the transport refuses: the
+  /// rest of the batch would block for the same drain timeout each and the
+  /// host needs the snapshot anyway (on_send_failed). Returns whether every
+  /// frame was taken.
+  bool send(const std::shared_ptr<Sink> &sink, const std::vector<OutMsg> &out) {
     if (!sink)
-      return;
-    std::lock_guard<std::mutex> lock(sink->mutex);
-    if (!sink->send)
-      return;
-    for (const auto &m : out) {
-      const auto frame = detail::dp::build_frame(m.type, m.payload, sink->module, m.correlation);
-      if (frame.empty()) {
-        logger_.warn_rate_limited("dropping an oversized frame ({} bytes of payload)",
-                                  m.payload.size());
-        continue;
+      return false;
+    size_t failed_bytes = 0;
+    {
+      std::lock_guard<std::mutex> lock(sink->mutex);
+      if (!sink->send)
+        return false;
+      for (const auto &m : out) {
+        const auto frame = detail::dp::build_frame(m.type, m.payload, sink->module, m.correlation);
+        if (frame.empty()) {
+          logger_.warn_rate_limited("dropping an oversized frame ({} bytes of payload)",
+                                    m.payload.size());
+          continue;
+        }
+        if (!sink->send(frame)) {
+          failed_bytes = frame.size();
+          break;
+        }
       }
-      if (!sink->send(frame) && !sink->needs_resync.exchange(true))
-        logger_.warn("sink {} could not take a {}-byte frame; the host must resync "
-                     "(GET_DESKTOP)",
-                     sink->id, frame.size());
     }
+    if (failed_bytes)
+      on_send_failed(sink, failed_bytes);
+    return failed_bytes == 0;
   }
 
 private:
diff --git a/components/desktop/include/desktop_service.hpp b/components/desktop/include/desktop_service.hpp
index 83db5f84d8..0bafefc2e8 100644
--- a/components/desktop/include/desktop_service.hpp
+++ b/components/desktop/include/desktop_service.hpp
@@ -69,9 +69,10 @@ class DesktopService : public BaseComponent {
   /// Transmits one encoded frame to the host, all-or-nothing, and returns
   /// whether it was queued (unlike the other espp services' `send`, which is
   /// void: the desktop streams state, so a dropped frame must be known -- the
-  /// Desktop then flags this transport as needing a resync, see
-  /// needs_resync()). UsbDevice::write_vendor / write_cdc have exactly this
-  /// contract (bounded wait for FIFO room, never a partial frame).
+  /// Desktop then pauses streaming to this transport and re-sends the full
+  /// snapshot by itself once frames go through again, see needs_resync()).
+  /// UsbDevice::write_vendor / write_cdc have exactly this contract (bounded
+  /// wait for FIFO room, never a partial frame).
   using send_fn = std::function<bool(std::span<const uint8_t> frame)>;
 
   /// Configuration for the DesktopService.
@@ -118,8 +119,9 @@ class DesktopService : public BaseComponent {
   bool attached() const { return desktop_.sink_active(sink_); }
 
   /// @brief Whether a frame to this transport was dropped (send returned
-  ///        false) since the host's last GET_DESKTOP: its mirror of the
-  ///        desktop is incomplete until it resyncs.
+  ///        false) and the host's mirror is still incomplete: streaming is
+  ///        paused until the desktop's own snapshot gets through (retried
+  ///        with back-off) or the host sends GET_DESKTOP.
   bool needs_resync() const { return desktop_.sink_needs_resync(sink_); }
 
   /**
diff --git a/components/desktop/web/desktop.html b/components/desktop/web/desktop.html
index 61f4ea450c..a5176d27be 100644
--- a/components/desktop/web/desktop.html
+++ b/components/desktop/web/desktop.html
@@ -457,6 +457,15 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
     const HEADER_SIZE = 9, CRC_SIZE = 4;
     const MAX_PAYLOAD = 4096;
     const MAX_FRAME = HEADER_SIZE + MAX_PAYLOAD + CRC_SIZE;
+    // Bytes requested per bulk IN transfer. A bulk transfer ends on a short
+    // packet OR when the buffer is full, so when the device streams several
+    // max-size frames back-to-back (a 16 KiB log snapshot, a busy Log Viewer)
+    // every packet is full: the request length MUST then be a multiple of the
+    // endpoint's packet size, or the packet that straddles the buffer's end
+    // overruns it ("babble"/overflow) and the pipe errors out. Asking for the
+    // frame size (4111 B) did exactly that once the console held > 4 KiB.
+    // 16 KiB is a multiple of every bulk packet size (64 FS / 512 HS / 1024 SS).
+    const USB_READ_BYTES = 16384;
     // The dispatcher module byte is only a routing key: the desktop service is
     // published on module 9 by default, but a device may serve it on any id.
     // It is resolved on connect from the device's discovery reply (by the
@@ -1345,6 +1354,8 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
         if (found.alternateSetting !== 0)
           await device.selectAlternateInterface(found.interfaceNumber, found.alternateSetting);
         const epIn = found.inEp.endpointNumber, epOut = found.outEp.endpointNumber;
+        const inPacket = found.inEp.packetSize > 0 ? found.inEp.packetSize : 64;
+        const readLen = Math.max(1, Math.ceil(USB_READ_BYTES / inPacket)) * inPacket; // see USB_READ_BYTES
         const t = {
           kind: "usb",
           name: (device.productName || "USB device") + " (" +
@@ -1375,7 +1386,7 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
         (async () => {
           for (;;) {
             let result;
-            try { result = await device.transferIn(epIn, MAX_FRAME); }
+            try { result = await device.transferIn(epIn, readLen); }
             catch (e) {
               if (!t.closing) { logLine("err", "USB read error: " + e.message); onTransportGone(t); }
               return;

From fe71a31dbd4cfab7651cdee04e99a2cf692d1e49 Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 14:30:49 -0500
Subject: [PATCH 04/10] fix(desktop): reactivate a sink after a successful
 automatic resync; babble recovery in the page

Review round 3 (Copilot): resync_if_due() never cleared needs_resync after
the snapshot was taken, so the sink stayed paused and -- resync_due not
being re-armed on success -- the retry fired on every task iteration: on
the board the device streamed whole snapshots 80 times a second as soon as
the host accepted frames. send_snapshot() now returns whether every frame
was taken; on success the flag is cleared and the sink reactivated, unless a
concurrent detach() cleared the flag first (then it stays inactive).

desktop.html: a "babble" transferIn status is recovered like a stall
(clearHalt + continue), the way the OTA / ODrive consoles do, instead of
the read loop dying -- defense in depth behind the packet-aligned reads.

Hardware (CDC, host gone 12 s, System Monitor + Log Viewer open): 1.3 s
after the host came back the device sent one unsolicited DESKTOP + two
snapshot WINDOW_OPENs and resumed deltas (108 WIDGET_SETs in 11 s, no
repeat snapshot); GET_DESKTOP answered in 9.8 ms.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/include/desktop.hpp | 22 ++++++++++++----------
 components/desktop/web/desktop.html    |  6 +++++-
 2 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/components/desktop/include/desktop.hpp b/components/desktop/include/desktop.hpp
index f2d8e69761..3a40a3f532 100644
--- a/components/desktop/include/desktop.hpp
+++ b/components/desktop/include/desktop.hpp
@@ -1319,16 +1319,16 @@ class Desktop : public BaseComponent {
       sink->active = true;
       sink->needs_resync.store(false); // this reply is the resync
     }
-    const size_t frames = send_snapshot(sink, cmd.correlation);
-    logger_.debug("GET_DESKTOP from sink {}: {} frames", cmd.sink, frames);
+    const bool ok = send_snapshot(sink, cmd.correlation);
+    logger_.debug("GET_DESKTOP from sink {}: snapshot {}", cmd.sink, ok ? "sent" : "NOT taken");
   }
 
   /// Encode the full state (DESKTOP, then one WINDOW_OPEN snapshot per window
   /// and the open dialogs) under the lock and send it to one sink outside it:
   /// the GET_DESKTOP reply (`correlation` echoed on the DESKTOP frame) or a
-  /// device-initiated resync (no correlation). Returns the number of frames
-  /// built (whether they were all taken is tracked by send()).
-  size_t send_snapshot(const std::shared_ptr<Sink> &sink, std::optional<uint16_t> correlation) {
+  /// device-initiated resync (no correlation). Returns whether the sink took
+  /// every frame (a refused one pauses the sink, see send()).
+  bool send_snapshot(const std::shared_ptr<Sink> &sink, std::optional<uint16_t> correlation) {
     std::vector<OutMsg> out{};
     {
       std::lock_guard<std::recursive_mutex> lock(mutex_);
@@ -1346,8 +1346,7 @@ class Desktop : public BaseComponent {
       if (dropped)
         logger_.warn("snapshot: {} oversized properties dropped", dropped);
     }
-    send(sink, out);
-    return out.size();
+    return send(sink, out);
   }
 
   /// Device-initiated resync: a sink that dropped a frame (inactive since) is
@@ -1368,10 +1367,13 @@ class Desktop : public BaseComponent {
                    });
     }
     for (const auto &sink : due) {
-      send_snapshot(sink, std::nullopt);
+      const bool ok = send_snapshot(sink, std::nullopt);
       std::lock_guard<std::recursive_mutex> lock(mutex_);
-      if (sink->needs_resync.load())
-        continue; // a frame failed again: on_send_failed() re-armed the retry
+      if (!ok)
+        continue; // a frame was refused again: on_send_failed() re-armed the retry
+      if (!sink->needs_resync.load())
+        continue; // detached meanwhile (set_sink_active(false) cleared the flag): stay inactive
+      sink->needs_resync.store(false);
       sink->active = true;
       logger_.info("sink {} took the snapshot again; streaming to it resumed", sink->id);
     }
diff --git a/components/desktop/web/desktop.html b/components/desktop/web/desktop.html
index a5176d27be..2b475b19f9 100644
--- a/components/desktop/web/desktop.html
+++ b/components/desktop/web/desktop.html
@@ -1392,7 +1392,11 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
               return;
             }
             if (t.closing) return;
-            if (result.status === "stall") {
+            if (result.status === "stall" || result.status === "babble") {
+              // babble = the device offered more than the buffer took (cannot
+              // happen with packet-aligned reads, see USB_READ_BYTES); recover
+              // like the OTA / ODrive consoles do instead of dying
+              if (result.status === "babble") logLine("warn", "USB IN babble; clearing the endpoint and continuing.");
               try { await device.clearHalt("in", epIn); } catch (_) {}
               continue;
             }

From 399121ecbaf77e6743a91e186e8dddbdcf3b8e06 Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 14:40:29 -0500
Subject: [PATCH 05/10] fix(desktop): reactivate a resynced sink only if its
 state did not change meanwhile

Review round 4 (Copilot): between the snapshot send (sink mutex released)
and the reactivation (model mutex taken) another task may refuse a direct
send to the same sink (e.g. the queue-full ERROR reply in submit()) or the
transport may detach; the flag was already true, so the older successful
snapshot would have masked the newer failure. Each sink now carries a
generation bumped by every state change (refused frame, attach, detach);
resync_if_due() captures it with the due sink and reactivates only when it
is unchanged after the snapshot.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/include/desktop.hpp | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/components/desktop/include/desktop.hpp b/components/desktop/include/desktop.hpp
index 3a40a3f532..fc82d8efe6 100644
--- a/components/desktop/include/desktop.hpp
+++ b/components/desktop/include/desktop.hpp
@@ -948,6 +948,7 @@ class Desktop : public BaseComponent {
     std::lock_guard<std::recursive_mutex> lock(mutex_);
     if (auto s = find_sink(id)) {
       s->active = active;
+      ++s->generation;
       if (!active)
         s->needs_resync.store(
             false); // detached: no host to resync (the next GET_DESKTOP re-attaches)
@@ -1150,6 +1151,10 @@ class Desktop : public BaseComponent {
     std::atomic<bool> needs_resync{false};
     std::chrono::steady_clock::time_point resync_due{}; ///< guarded by mutex_
     std::chrono::milliseconds resync_retry{0};          ///< current back-off, guarded by mutex_
+    /// Bumped by every state change (a refused frame, attach / detach); a
+    /// resync reactivates the sink only if nothing changed while its snapshot
+    /// was in flight. Guarded by mutex_.
+    uint32_t generation{0};
   };
 
   /// The wire type of a command's request (for an ERROR reply).
@@ -1318,6 +1323,7 @@ class Desktop : public BaseComponent {
         return;
       sink->active = true;
       sink->needs_resync.store(false); // this reply is the resync
+      ++sink->generation;
     }
     const bool ok = send_snapshot(sink, cmd.correlation);
     logger_.debug("GET_DESKTOP from sink {}: snapshot {}", cmd.sink, ok ? "sent" : "NOT taken");
@@ -1357,24 +1363,25 @@ class Desktop : public BaseComponent {
   /// an unsolicited DESKTOP (complete window list) + snapshot WINDOW_OPENs as
   /// authoritative, so this heals its mirror without a request.
   void resync_if_due() {
-    std::vector<std::shared_ptr<Sink>> due{};
+    std::vector<std::pair<std::shared_ptr<Sink>, uint32_t>> due{}; // sink + its generation
     {
       std::lock_guard<std::recursive_mutex> lock(mutex_);
       const auto now = std::chrono::steady_clock::now();
-      std::copy_if(sinks_.begin(), sinks_.end(), std::back_inserter(due),
-                   [now](const std::shared_ptr<Sink> &s) {
-                     return s->needs_resync.load() && !s->active && now >= s->resync_due;
-                   });
+      for (const auto &s : sinks_)
+        if (s->needs_resync.load() && !s->active && now >= s->resync_due)
+          due.emplace_back(s, s->generation);
     }
-    for (const auto &sink : due) {
+    for (const auto &[sink, gen] : due) {
       const bool ok = send_snapshot(sink, std::nullopt);
       std::lock_guard<std::recursive_mutex> lock(mutex_);
       if (!ok)
         continue; // a frame was refused again: on_send_failed() re-armed the retry
-      if (!sink->needs_resync.load())
-        continue; // detached meanwhile (set_sink_active(false) cleared the flag): stay inactive
+      if (sink->generation != gen)
+        continue; // changed while the snapshot was in flight (a concurrent send was
+                  // refused, or the transport detached / re-attached): that state wins
       sink->needs_resync.store(false);
       sink->active = true;
+      ++sink->generation;
       logger_.info("sink {} took the snapshot again; streaming to it resumed", sink->id);
     }
   }
@@ -1385,6 +1392,7 @@ class Desktop : public BaseComponent {
   void on_send_failed(const std::shared_ptr<Sink> &sink, size_t frame_bytes) {
     std::lock_guard<std::recursive_mutex> lock(mutex_);
     sink->active = false;
+    ++sink->generation;
     if (!sink->needs_resync.exchange(true)) {
       sink->resync_retry = kResyncRetryMin;
       logger_.warn("sink {} could not take a {}-byte frame; streaming to it is paused until it "

From f40679ba4220549b737b42924dbe3cc537f00a7b Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 15:57:24 -0500
Subject: [PATCH 06/10] fix(desktop): ignore a stale send failure after a
 detach / re-attach

Review round 5 (Copilot): the mirror image of the previous race. send()
releases the sink mutex before reporting a refused frame, so a detach
(set_sink_active(false)) or a new GET_DESKTOP attach could land first and
the old failure then re-armed retries against the detached transport or
paused the new session. send() now captures the sink generation before the
transport callback and on_send_failed() applies the failure only while that
generation is current.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/include/desktop.hpp | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/components/desktop/include/desktop.hpp b/components/desktop/include/desktop.hpp
index fc82d8efe6..b8fa52d663 100644
--- a/components/desktop/include/desktop.hpp
+++ b/components/desktop/include/desktop.hpp
@@ -1388,9 +1388,13 @@ class Desktop : public BaseComponent {
 
   /// A sink's transport dropped a frame: stop streaming to it and schedule the
   /// device-initiated resync (see send_fn). Called by send() after it released
-  /// the sink's mutex (this takes mutex_; the two are never held together).
-  void on_send_failed(const std::shared_ptr<Sink> &sink, size_t frame_bytes) {
+  /// the sink's mutex (this takes mutex_; the two are never held together) with
+  /// the generation send() captured before the callback: a detach, a new
+  /// attach or another failure in the meantime makes this one stale.
+  void on_send_failed(const std::shared_ptr<Sink> &sink, size_t frame_bytes, uint32_t gen) {
     std::lock_guard<std::recursive_mutex> lock(mutex_);
+    if (sink->generation != gen)
+      return; // stale: the sink detached, re-attached or already failed while this send ran
     sink->active = false;
     ++sink->generation;
     if (!sink->needs_resync.exchange(true)) {
@@ -1598,6 +1602,11 @@ class Desktop : public BaseComponent {
   bool send(const std::shared_ptr<Sink> &sink, const std::vector<OutMsg> &out) {
     if (!sink)
       return false;
+    uint32_t gen = 0;
+    {
+      std::lock_guard<std::recursive_mutex> lock(mutex_);
+      gen = sink->generation; // a failure below applies only to THIS state of the sink
+    }
     size_t failed_bytes = 0;
     {
       std::lock_guard<std::mutex> lock(sink->mutex);
@@ -1617,7 +1626,7 @@ class Desktop : public BaseComponent {
       }
     }
     if (failed_bytes)
-      on_send_failed(sink, failed_bytes);
+      on_send_failed(sink, failed_bytes, gen);
     return failed_bytes == 0;
   }
 

From a75e059a4b2f62e648085313cefd58fe9b30e58a Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 16:29:48 -0500
Subject: [PATCH 07/10] fix(desktop): keep a paused sink attached; document the
 automatic resync in the guide

Review round 6 (Copilot, summary-only): a refused frame used to clear the
sink's `active` flag, so DesktopService::attached() reported a transient
backpressure event as a detach. `active` is now purely attachment (GET_DESKTOP
/ detach), `needs_resync` is the pause: broadcasts go to attached sinks that
are not paused, the automatic resync retries attached paused sinks, and a
successful snapshot only clears the pause. The Sphinx guide and the service
header now describe the retry/back-off behaviour instead of "until the next
GET_DESKTOP"; the send_fn sentence lost its nested parenthesis.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/include/desktop.hpp        | 42 +++++++++++--------
 .../desktop/include/desktop_service.hpp       | 22 ++++++----
 doc/en/desktop/desktop.rst                    |  7 +++-
 3 files changed, 42 insertions(+), 29 deletions(-)

diff --git a/components/desktop/include/desktop.hpp b/components/desktop/include/desktop.hpp
index b8fa52d663..1647032504 100644
--- a/components/desktop/include/desktop.hpp
+++ b/components/desktop/include/desktop.hpp
@@ -1145,9 +1145,13 @@ class Desktop : public BaseComponent {
     uint8_t module{detail::dp::kModule};
     send_fn send{nullptr};
     std::mutex mutex; ///< held across `send` so this sink's frames never interleave
+    /// Attached: a host asked for the desktop on this transport (GET_DESKTOP)
+    /// and it was not detached since (set_sink_active). Only attached sinks
+    /// receive broadcasts; a refused frame does NOT clear this (see needs_resync).
     bool active{false};
-    /// A frame was dropped and no snapshot got through since: the sink is
-    /// inactive and resync_if_due() re-sends the snapshot at `resync_due`.
+    /// A frame was refused and no snapshot got through since: streaming to the
+    /// (still attached) sink is paused and resync_if_due() re-sends the
+    /// snapshot at `resync_due`.
     std::atomic<bool> needs_resync{false};
     std::chrono::steady_clock::time_point resync_due{}; ///< guarded by mutex_
     std::chrono::milliseconds resync_retry{0};          ///< current back-off, guarded by mutex_
@@ -1263,7 +1267,7 @@ class Desktop : public BaseComponent {
       if (model_.dirty.any())
         next = std::min(next, last_flush_ + config_.flush_period);
       for (const auto &s : sinks_)
-        if (s->needs_resync.load() && !s->active)
+        if (s->active && s->needs_resync.load())
           next = std::min(next, s->resync_due);
     }
     std::unique_lock<std::mutex> lock(m);
@@ -1355,11 +1359,11 @@ class Desktop : public BaseComponent {
     return send(sink, out);
   }
 
-  /// Device-initiated resync: a sink that dropped a frame (inactive since) is
-  /// sent the full snapshot again once its retry time comes. While the
-  /// transport still refuses frames each attempt costs one failed write and
-  /// the retry backs off; once the whole snapshot is taken the sink is active
-  /// again and the following flushes stream deltas to it. The browser treats
+  /// Device-initiated resync: an attached sink whose streaming is paused
+  /// (needs_resync) is sent the full snapshot again once its retry time comes.
+  /// While the transport still refuses frames each attempt costs one failed
+  /// write and the retry backs off; once the whole snapshot is taken streaming
+  /// resumes and the following flushes send deltas to it. The browser treats
   /// an unsolicited DESKTOP (complete window list) + snapshot WINDOW_OPENs as
   /// authoritative, so this heals its mirror without a request.
   void resync_if_due() {
@@ -1368,7 +1372,7 @@ class Desktop : public BaseComponent {
       std::lock_guard<std::recursive_mutex> lock(mutex_);
       const auto now = std::chrono::steady_clock::now();
       for (const auto &s : sinks_)
-        if (s->needs_resync.load() && !s->active && now >= s->resync_due)
+        if (s->active && s->needs_resync.load() && now >= s->resync_due)
           due.emplace_back(s, s->generation);
     }
     for (const auto &[sink, gen] : due) {
@@ -1379,8 +1383,9 @@ class Desktop : public BaseComponent {
       if (sink->generation != gen)
         continue; // changed while the snapshot was in flight (a concurrent send was
                   // refused, or the transport detached / re-attached): that state wins
-      sink->needs_resync.store(false);
-      sink->active = true;
+      if (!sink->active)
+        continue;                      // (cannot happen with an unchanged generation; defensive)
+      sink->needs_resync.store(false); // paused no more (it stayed attached throughout)
       ++sink->generation;
       logger_.info("sink {} took the snapshot again; streaming to it resumed", sink->id);
     }
@@ -1395,8 +1400,7 @@ class Desktop : public BaseComponent {
     std::lock_guard<std::recursive_mutex> lock(mutex_);
     if (sink->generation != gen)
       return; // stale: the sink detached, re-attached or already failed while this send ran
-    sink->active = false;
-    ++sink->generation;
+    ++sink->generation; // the sink stays attached (attached()); streaming is paused by needs_resync
     if (!sink->needs_resync.exchange(true)) {
       sink->resync_retry = kResyncRetryMin;
       logger_.warn("sink {} could not take a {}-byte frame; streaming to it is paused until it "
@@ -1567,9 +1571,10 @@ class Desktop : public BaseComponent {
     flush_now();
   }
 
-  /// Encode everything pending (under the lock) and send it to every active
-  /// sink (outside it). With no active sink the changes are simply dropped:
-  /// the next GET_DESKTOP replays the full state anyway.
+  /// Encode everything pending (under the lock) and send it to every attached
+  /// sink whose streaming is not paused (outside it). With no such sink the
+  /// changes are simply dropped: the next snapshot (GET_DESKTOP or the
+  /// automatic resync) replays the full state anyway.
   void flush_now() {
     std::vector<OutMsg> out{};
     std::vector<std::shared_ptr<Sink>> targets{};
@@ -1584,8 +1589,9 @@ class Desktop : public BaseComponent {
         logger_.warn("flush: {} oversized properties dropped (max payload {})", dropped,
                      max_payload());
       last_flush_ = std::chrono::steady_clock::now();
-      std::copy_if(sinks_.begin(), sinks_.end(), std::back_inserter(targets),
-                   [](const std::shared_ptr<Sink> &s) { return s->active; });
+      std::copy_if(
+          sinks_.begin(), sinks_.end(), std::back_inserter(targets),
+          [](const std::shared_ptr<Sink> &s) { return s->active && !s->needs_resync.load(); });
     }
     if (out.empty())
       return;
diff --git a/components/desktop/include/desktop_service.hpp b/components/desktop/include/desktop_service.hpp
index 0bafefc2e8..79b8ac9920 100644
--- a/components/desktop/include/desktop_service.hpp
+++ b/components/desktop/include/desktop_service.hpp
@@ -40,11 +40,14 @@ namespace espp {
  *
  * GET_DESKTOP answers with the DESKTOP snapshot (apps, settings, open
  * windows) followed by the full tree of every open window and every open
- * dialog, and marks this transport active: from then on the Desktop
+ * dialog, and marks this transport attached: from then on the Desktop
  * broadcasts its changes (WINDOW_OPEN / WIDGET_SET / ... ) to it until
  * detach() (e.g. on USB unmount) or until the next GET_DESKTOP after a
- * reconnect. LAUNCH_APP / CLOSE_WINDOW are acknowledged with OK / ERROR; the
- * events (WINDOW_EVENT / WIDGET_EVENT / DIALOG_RESULT) are not.
+ * reconnect. A frame the transport refuses pauses the broadcasts (the
+ * transport stays attached, needs_resync() is true) until the Desktop's own
+ * retried snapshot gets through or the host sends GET_DESKTOP. LAUNCH_APP /
+ * CLOSE_WINDOW are acknowledged with OK / ERROR; the events (WINDOW_EVENT /
+ * WIDGET_EVENT / DIALOG_RESULT) are not.
  *
  * **Threading**: an internal mutex covers the parser; the only frame this
  * object sends itself is the ERROR for a malformed request, serialized on a
@@ -67,10 +70,10 @@ class DesktopService : public BaseComponent {
   static constexpr uint16_t kProtocolVersion = espp::detail::desktop_protocol::kProtocolVersion;
 
   /// Transmits one encoded frame to the host, all-or-nothing, and returns
-  /// whether it was queued (unlike the other espp services' `send`, which is
-  /// void: the desktop streams state, so a dropped frame must be known -- the
-  /// Desktop then pauses streaming to this transport and re-sends the full
-  /// snapshot by itself once frames go through again, see needs_resync()).
+  /// whether it was queued. Unlike the other espp services' `send`, which is
+  /// void, this one must report a refused frame: the desktop streams state,
+  /// so it then pauses streaming to this transport and re-sends the full
+  /// snapshot by itself once frames go through again, see needs_resync().
   /// UsbDevice::write_vendor / write_cdc have exactly this contract (bounded
   /// wait for FIFO room, never a partial frame).
   using send_fn = std::function<bool(std::span<const uint8_t> frame)>;
@@ -120,8 +123,9 @@ class DesktopService : public BaseComponent {
 
   /// @brief Whether a frame to this transport was dropped (send returned
   ///        false) and the host's mirror is still incomplete: streaming is
-  ///        paused until the desktop's own snapshot gets through (retried
-  ///        with back-off) or the host sends GET_DESKTOP.
+  ///        paused (the transport stays attached()) until the desktop's own
+  ///        snapshot gets through (retried with back-off) or the host sends
+  ///        GET_DESKTOP.
   bool needs_resync() const { return desktop_.sink_needs_resync(sink_); }
 
   /**
diff --git a/doc/en/desktop/desktop.rst b/doc/en/desktop/desktop.rst
index a96175a56e..bdb4f6ea9d 100644
--- a/doc/en/desktop/desktop.rst
+++ b/doc/en/desktop/desktop.rst
@@ -46,8 +46,11 @@ notifications and the app registry are single frames whose limits the API
 enforces (an oversized dialog / toast / title / placeholder / tooltip /
 column set is refused and logged, the registry is bounded in app count and
 string lengths). The transport's ``send`` reports
-whether a frame was queued, and a transport that dropped one is flagged as
-needing a resync until the host's next ``GET_DESKTOP``; the wire format
+whether a frame was queued; when one is refused (the host went away or
+stopped reading) the desktop pauses streaming to that transport
+(``needs_resync()``, it stays attached) and re-sends the full snapshot by
+itself once frames go through again, retrying every second with back-off
+to eight seconds, or at the host's next ``GET_DESKTOP``; the wire format
 is documented in ``include/detail/desktop_protocol.hpp`` and checked by a
 host test against the fixture ``test/desktop_vectors.txt``, which the web
 app's test reads too.

From 6ef9d7bb686a066203fa2b2b0594b6027f96d574 Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 21:27:26 -0500
Subject: [PATCH 08/10] refactor(desktop): track the TextArea byte size
 incrementally; one eviction helper for both bounds

Review round 7 (Copilot): wd.trim() rebuilt and UTF-8-encoded the whole
text on every append. The widget now keeps `bytes` (the UTF-8 size of the
lines joined by "\n", what the device counts) up to date on append /
setText / eviction and only joins + encodes when the bound is exceeded.
Line eviction (model + console DOM) lives in one dropFirstLine() helper
used by the MaxLines and the MaxTextBytes paths; the edit-mode textarea is
re-synced only when a trim changed something. Selftest asserts the counter
matches the text after the cuts.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/web/desktop.html | 54 +++++++++++++++++++----------
 1 file changed, 35 insertions(+), 19 deletions(-)

diff --git a/components/desktop/web/desktop.html b/components/desktop/web/desktop.html
index 2b475b19f9..0e66b84c20 100644
--- a/components/desktop/web/desktop.html
+++ b/components/desktop/web/desktop.html
@@ -3025,7 +3025,10 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
         // colours, auto-scroll and optional Key events)
         create(wd) {
           const el = document.createElement("div"); el.className = "w-textarea";
-          wd.st = { lines: [{ raw: "", startState: null }], maxLines: MAX_LINES_DEFAULT, flags: 0, mode: null, dirty: false, lastScroll: -1 };
+          // `bytes` = the UTF-8 size of the lines joined by "\n" (what the device
+          // counts against MaxTextBytes), kept incrementally so an append does
+          // not re-encode the whole text
+          wd.st = { lines: [{ raw: "", startState: null }], bytes: 0, maxLines: MAX_LINES_DEFAULT, flags: 0, mode: null, dirty: false, lastScroll: -1 };
           const idle = throttle(() => { if (wd.st.mode === "edit" && wd.st.dirty) { wd.st.dirty = false; sendText(wd, wd.inner.value); } }, TEXT_IDLE_MS);
           wd.idle = idle;
           wd.setMode = (mode) => {
@@ -3082,40 +3085,51 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
             }
             if (wd.st.flags & TA_FLAG.AUTO_SCROLL) wd.inner.scrollTop = wd.inner.scrollHeight;
           };
+          // Evict the first line from the model AND the console DOM together (both
+          // bounds use this, so the two never drift). Only called with 2+ lines.
+          wd.dropFirstLine = () => {
+            const l = wd.st.lines.shift();
+            wd.st.bytes -= utf8ByteLength(l.raw) + 1; // + the newline that joined it
+            if (wd.st.mode === "console" && wd.inner.firstChild) wd.inner.removeChild(wd.inner.firstChild);
+          };
           wd.trim = () => {
+            let changed = false;
             const max = wd.st.maxLines;
             if (max) {
-              while (wd.st.lines.length > max) {
-                wd.st.lines.shift();
-                if (wd.st.mode === "console" && wd.inner.firstChild) wd.inner.removeChild(wd.inner.firstChild);
-              }
+              while (wd.st.lines.length > max) { wd.dropFirstLine(); changed = true; }
             }
             // the device keeps at most MaxTextBytes and applies this same rule
             // to ITS copy on every append, so appends stay appends on the wire.
             // Dropping leading lines leaves the surviving console nodes valid:
             // each line was rendered from the ANSI state the removed text really
-            // produced, and that state stays on the line (`startState`).
-            const raw = wd.st.lines.map((l) => l.raw).join("\n");
-            const bounded = boundTextBytes(raw, settings.maxTextBytes);
-            if (bounded !== raw) {
-              const kept = bounded.split("\n");
-              const drop = wd.st.lines.length - kept.length;
-              for (let i = 0; i < drop; i++) { wd.st.lines.shift(); if (wd.st.mode === "console" && wd.inner.firstChild) wd.inner.removeChild(wd.inner.firstChild); }
-              const first = wd.st.lines[0];
-              if (first && first.raw !== kept[0]) {
-                // a mid-line cut: the kept suffix starts in the ANSI state the removed prefix left behind
-                if (wd.st.flags & TA_FLAG.ANSI) first.startState = ansiSplit(first.raw.slice(0, first.raw.length - kept[0].length), first.startState).state;
-                first.raw = kept[0];
-                if (wd.st.mode === "console") wd.renderLine(0);
+            // produced, and that state stays on the line (`startState`). The
+            // joined text is only rebuilt + encoded when the bound is exceeded.
+            if (wd.st.bytes > settings.maxTextBytes) {
+              const raw = wd.st.lines.map((l) => l.raw).join("\n");
+              const bounded = boundTextBytes(raw, settings.maxTextBytes);
+              if (bounded !== raw) {
+                const kept = bounded.split("\n");
+                const drop = wd.st.lines.length - kept.length;
+                for (let i = 0; i < drop; i++) wd.dropFirstLine();
+                const first = wd.st.lines[0];
+                if (first && first.raw !== kept[0]) {
+                  // a mid-line cut: the kept suffix starts in the ANSI state the removed prefix left behind
+                  if (wd.st.flags & TA_FLAG.ANSI) first.startState = ansiSplit(first.raw.slice(0, first.raw.length - kept[0].length), first.startState).state;
+                  first.raw = kept[0];
+                  if (wd.st.mode === "console") wd.renderLine(0);
+                }
+                changed = true;
               }
+              wd.st.bytes = utf8ByteLength(bounded);
             }
             // edit mode: the <textarea> follows the device's copy after either
             // bound, unless the user is mid-edit (their text is sent whole and
             // the device bounds + echoes it)
-            if (wd.st.mode === "edit" && !wd.st.dirty) { const v = wd.st.lines.map((l) => l.raw).join("\n"); if (wd.inner.value !== v) wd.inner.value = v; }
+            if (changed && wd.st.mode === "edit" && !wd.st.dirty) { const v = wd.st.lines.map((l) => l.raw).join("\n"); if (wd.inner.value !== v) wd.inner.value = v; }
           };
           wd.append = (text) => {
             const parts = String(text).split("\n");
+            wd.st.bytes += utf8ByteLength(String(text)); // newlines included: they join the new lines
             const stick = wd.st.mode === "console" && (wd.st.flags & TA_FLAG.AUTO_SCROLL) && wd.atBottom();
             const last = wd.st.lines.length - 1;
             wd.st.lines[last].raw += parts[0];
@@ -3132,6 +3146,7 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
           };
           wd.setText = (text) => {
             wd.st.lines = String(text).split("\n").map((raw) => ({ raw, startState: null }));
+            wd.st.bytes = utf8ByteLength(String(text));
             if (wd.st.mode === "edit") { wd.inner.value = String(text); wd.st.dirty = false; }
             wd.trim(); // line bound, then the device's byte bound (edit mode: inner.value follows)
             if (wd.st.mode === "console") wd.renderAll();
@@ -3695,6 +3710,7 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
         app("abcdefghijklmnopqrstuvwxyz"); // 26 B on the last line: no newline after the cut, so it lands mid-line
         assert(rawOf() === "cdefghijklmnopqrstuvwxyz" && cw.inner.children.length === 1, "mid-line cut drops the earlier lines and shortens the first: " + JSON.stringify(rawOf()));
         assert(cw.inner.children[0].textContent === "cdefghijklmnopqrstuvwxyz", "first line re-rendered after a mid-line cut");
+        assert(cw.st.bytes === utf8ByteLength(rawOf()), "the incremental byte counter matches the text after the cuts: " + cw.st.bytes);
         // an ANSI console: a mid-line cut keeps the colour the removed prefix switched on
         feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "10" + "0200" + "1100"); // Flags: ReadOnly | Ansi
         feedHex(DT.WIDGET_SET, "0100" + "01" + "6000" + "01" + "01" + "0000"); // Text ""

From 1009c5e81162e4ae136074c805e22b6f1f45fdc0 Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 21:49:56 -0500
Subject: [PATCH 09/10] feat(desktop): DESKTOP flag bit2 Snapshot makes a
 snapshot authoritative for dialogs

Review round 8 (Copilot): the automatic resync (and a same-session
GET_DESKTOP) could not heal a refused DIALOG_CLOSE -- Model::snapshot()
only re-sends open dialogs and the browser never dropped the absent ones,
so a stale modal survived. The snapshot DESKTOP (GET_DESKTOP reply and the
device-initiated resync, never the apps / records change broadcast) now
carries flags bit2 Snapshot; the browser drops every local dialog when it
sees it (or when the DESKTOP answers its own request) before the DIALOG
frames that follow re-create the live ones. Windows keep the existing rule
(reconciled against a complete window list). Selftest: a dialog survives
a plain broadcast and is dropped by a snapshot DESKTOP. Old hosts ignore
the bit.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/README.md                      |  2 +-
 components/desktop/include/desktop.hpp            |  6 ++++--
 .../desktop/include/detail/desktop_protocol.hpp   |  9 +++++++++
 components/desktop/web/desktop.html               | 15 +++++++++++++++
 4 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/components/desktop/README.md b/components/desktop/README.md
index 0b1d67c7cd..9ecdaa0a9e 100644
--- a/components/desktop/README.md
+++ b/components/desktop/README.md
@@ -113,7 +113,7 @@ fields are little-endian; `str8` = `[len u8][utf8]`, `str16` = `[len u16][utf8]`
 | `0x04` WINDOW_EVENT | H→D | `[win u16][ev u8][x i16][y i16][w u16][h u16]` ev: 1 Focus 2 Blur 3 Minimize 4 Restore 5 Maximize 6 Moved 7 Resized (no ack) |
 | `0x05` WIDGET_EVENT | H→D | `[win u16][widget u16][ev u8][value]` ev: 1 Click · 2 Change `[i32]` · 3 Submit `[utf8]` · 4 Text `[offset u32][total u32][bytes]` (chunked) · 5 Select `[i32]` · 6 Activate `[i32]` · 7 Key `[key u16][mods u8][codepoint u32]` · 8 Scroll `[i32]` (no ack) |
 | `0x06` DIALOG_RESULT | H→D | `[dialog u16][button u8 (0xFF dismissed)][text utf8 rest]` (no ack) |
-| `0x81` DESKTOP | D→H | `[proto u8=1][flags u8 bit0 HasSnapshot bit1 WindowListComplete][rec count u8]{rec}[app count u8]{[id u8][flags u8 bit0 SingleInstance bit1 Hidden][name str8][icon str8][desc str8]}[win count u8]{[win u16][app u8]}`; recs: 1 DeviceName 2 Firmware 3 Theme 4 Accent u32 5 MaxPayload u16 6 FlushPeriodMs u16 7 MaxTextBytes u32 (the most text a TextArea holds / a host may send for one widget; a longer edit keeps its tail and is echoed back). Also sent when apps / settings change |
+| `0x81` DESKTOP | D→H | `[proto u8=1][flags u8 bit0 HasSnapshot bit1 WindowListComplete bit2 Snapshot (a full snapshot — GET_DESKTOP reply or the device's own resync: the host drops its dialogs and, with a complete list, unlisted windows before the frames that follow re-create them)][rec count u8]{rec}[app count u8]{[id u8][flags u8 bit0 SingleInstance bit1 Hidden][name str8][icon str8][desc str8]}[win count u8]{[win u16][app u8]}`; recs: 1 DeviceName 2 Firmware 3 Theme 4 Accent u32 5 MaxPayload u16 6 FlushPeriodMs u16 7 MaxTextBytes u32 (the most text a TextArea holds / a host may send for one widget; a longer edit keeps its tail and is echoed back). Also sent when apps / settings change |
 | `0x82` WINDOW_OPEN | D→H | `[win u16][app u8][flags u16][x i16][y i16][w u16][h u16][title str8][widget total u16][count u16]{widget rec}`; the rest of the tree follows in WIDGET_ADD |
 | `0x83` WINDOW_CLOSE | D→H | `[win u16][reason u8: 0 app 1 host 2 shutdown]` |
 | `0x84` WIDGET_SET | D→H | `[win u16][entries u8]{[widget u16][props u8]{rec}}`; widget 0 = the window (Title / WindowFlags / Geometry / Focus) |
diff --git a/components/desktop/include/desktop.hpp b/components/desktop/include/desktop.hpp
index 1647032504..24e26c3125 100644
--- a/components/desktop/include/desktop.hpp
+++ b/components/desktop/include/desktop.hpp
@@ -1344,9 +1344,11 @@ class Desktop : public BaseComponent {
       std::lock_guard<std::recursive_mutex> lock(mutex_);
       const bool has_snapshot = !model_.windows().empty() || !model_.dialogs().empty();
       bool trimmed = false;
+      auto info = model_.desktop_info(has_snapshot);
+      info.flags |=
+          detail::dp::kDesktopSnapshot; // authoritative: the host drops stale dialogs / windows
       out.push_back({.type = detail::dp::Type::Desktop,
-                     .payload = detail::dp::encode_desktop(model_.desktop_info(has_snapshot),
-                                                           max_payload(), &trimmed),
+                     .payload = detail::dp::encode_desktop(info, max_payload(), &trimmed),
                      .correlation = correlation});
       if (trimmed)
         logger_.warn("DESKTOP record set trimmed to fit {} bytes", max_payload());
diff --git a/components/desktop/include/detail/desktop_protocol.hpp b/components/desktop/include/detail/desktop_protocol.hpp
index fd6e233568..c9b131f962 100644
--- a/components/desktop/include/detail/desktop_protocol.hpp
+++ b/components/desktop/include/detail/desktop_protocol.hpp
@@ -31,6 +31,9 @@
 // Replies / events (device -> host, high bit set = frame reply flag):
 //   0x81 DESKTOP       [proto u8 = 1][flags u8][rec count u8]{rec}[app count u8]{app}
 //                      [win count u8]{[win u16][app u8]}
+//                      flags: bit0 HasSnapshot (WINDOW_OPEN(Snapshot) frames follow)
+//                      bit1 WindowListComplete bit2 Snapshot (a full snapshot: the
+//                      host drops its dialogs + unlisted windows, see kDesktopSnapshot)
 //                      app = [id u8][flags u8][name str8][icon str8][desc str8]
 //   0x82 WINDOW_OPEN   [win u16][app u8][flags u16][x i16][y i16][w u16][h u16]
 //                      [title str8][widget total u16][count u16]{widget rec}
@@ -184,6 +187,12 @@ inline constexpr uint8_t kDesktopHasSnapshot = 0x01; ///< WINDOW_OPEN(Snapshot)
 /// The window list is complete (set by the encoder unless it had to trim it):
 /// a host may close windows missing from it only when this bit is set.
 inline constexpr uint8_t kDesktopWindowListComplete = 0x02;
+/// This DESKTOP is a full snapshot (the GET_DESKTOP reply, or the device's
+/// own resync after a refused frame): the state of every open window and
+/// dialog follows it. A host drops every local dialog (the snapshot's DIALOG
+/// frames re-create the live ones) and, when the window list is complete,
+/// the windows missing from it. Clear on the change broadcast (apps / records).
+inline constexpr uint8_t kDesktopSnapshot = 0x04;
 
 /// Tags of the DESKTOP records.
 enum class DesktopTag : uint8_t {
diff --git a/components/desktop/web/desktop.html b/components/desktop/web/desktop.html
index 0e66b84c20..44ec98ac4c 100644
--- a/components/desktop/web/desktop.html
+++ b/components/desktop/web/desktop.html
@@ -681,6 +681,7 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
     const DESKTOP_PROTO = 1;                 // the `proto` byte at the head of every DESKTOP payload
     const DESKTOP_HAS_SNAPSHOT = 0x01;
     const DESKTOP_WINDOW_LIST_COMPLETE = 0x02;  // set when the window list is intact; a trimmed list is advisory, never authoritative
+    const DESKTOP_SNAPSHOT = 0x04;              // a full snapshot (GET_DESKTOP reply / the device's own resync): drop stale dialogs + unlisted windows
     const DESKTOP_MAX_PAYLOAD_CAP = 4081;    // stream_frame limit for a 4096-byte frame with a correlation id
     const DREC = { DEVICE_NAME: 1, FIRMWARE: 2, THEME: 3, ACCENT: 4, MAX_PAYLOAD: 5, FLUSH_PERIOD_MS: 6, MAX_TEXT_BYTES: 7 };
     const MAX_TEXT_BYTES_DEFAULT = 16384;     // DESKTOP record 7 absent: the largest reassembled host Text the device keeps
@@ -3416,6 +3417,11 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
       for (const a of info.apps) apps.set(a.id, a);
       renderApps();
       for (const w of windows.values()) { w.appName = appName(w.app); }
+      // a snapshot (the reply to our GET_DESKTOP, or the device's own resync after
+      // it had to drop frames to us) re-creates every live dialog right after
+      // this frame: local dialogs are stale until then (a DIALOG_CLOSE may have
+      // been among the dropped frames), so drop them all now
+      if (fromRequest || (info.flags & DESKTOP_SNAPSHOT)) { for (const d of [...dialogs.values()]) closeDialogLocal(d.id); }
       // a COMPLETE open-window list (bit1 set) is authoritative: drop what the
       // device no longer has; a trimmed one says nothing about unlisted windows
       if (!(info.flags & DESKTOP_WINDOW_LIST_COMPLETE)) {
@@ -3812,6 +3818,15 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
       const complete = Uint8Array.from(truncated); complete[1] = DESKTOP_WINDOW_LIST_COMPLETE;
       handleRxBytes(buildReplyFrame(moduleDesktop, DT.DESKTOP, complete));
       assert(!windows.has(1), "a complete empty window list drops the window");
+      // 13b. a dialog survives a plain DESKTOP broadcast (bit2 clear) but not a
+      // snapshot DESKTOP (bit2 set): its DIALOG frame would follow if it were live
+      feed("dialog");
+      assert(dialogs.size === 1, "dialog open before the broadcast");
+      handleRxBytes(buildReplyFrame(moduleDesktop, DT.DESKTOP, complete));
+      assert(dialogs.size === 1, "a change broadcast keeps the local dialog");
+      const snap = Uint8Array.from(complete); snap[1] = DESKTOP_WINDOW_LIST_COMPLETE | DESKTOP_SNAPSHOT;
+      handleRxBytes(buildReplyFrame(moduleDesktop, DT.DESKTOP, snap));
+      assert(dialogs.size === 0 && els.modal.hidden, "a snapshot DESKTOP drops the stale dialog");
       { // with no window (and no dialog) open, a real pointer hit on a desktop icon must reach the
         // icon: the full-size #windows layer must not swallow it (it did, until pointer-events: none)
         assert(els.modal.hidden, "no modal backdrop while probing the icons");

From 67a091654396780bd46fde6a23420ee7660876e8 Mon Sep 17 00:00:00 2001
From: William Emfinger <waemfinger@gmail.com>
Date: Mon, 5 Oct 2026 21:56:23 -0500
Subject: [PATCH 10/10] feat(desktop): espp.desktop protocol v2 (host-side
 MaxTextBytes on appends, Snapshot flag)

Review round 9 (Copilot): the host-side trimming and the DESKTOP Snapshot
flag change what a host must do, so the version negotiated through
discovery is now 2 (kProtocolVersion, the page's espp-protocols meta and
DESKTOP_PROTOCOL_VERSION, the docs and module tables). v1 was never
released (the component is unpublished and postdates the last tag); a v1
host would keep appending without trimming and could keep a stale dialog
after a resync. Every message layout is unchanged, so the DESKTOP
payload's own proto byte (kDesktopProto) stays 1 and the golden vectors
are untouched.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DFjjnq3XCTRAXENSxsCxJU
---
 components/desktop/README.md                          | 11 ++++++++---
 components/desktop/example/README.md                  |  2 +-
 .../desktop/include/detail/desktop_protocol.hpp       | 11 +++++++++--
 components/desktop/test/desktop_host_test.cpp         |  2 +-
 components/desktop/test/desktop_vectors.txt           |  2 +-
 components/desktop/web/desktop.html                   |  6 +++---
 components/desktop/web/test/desktop_codec_test.js     |  4 ++--
 components/dispatcher/README.md                       |  2 +-
 doc/en/desktop/desktop.rst                            |  2 +-
 doc/en/dispatcher/custom_modules.rst                  |  2 +-
 doc/en/dispatcher/dispatcher.rst                      |  2 +-
 11 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/components/desktop/README.md b/components/desktop/README.md
index 9ecdaa0a9e..11c285c7eb 100644
--- a/components/desktop/README.md
+++ b/components/desktop/README.md
@@ -15,7 +15,7 @@ user's actions back, over WebUSB / Web Serial (or any framed byte stream).
   timers and `post()`. Changes are coalesced and flushed by the desktop task
   every `flush_period`; every app callback runs on that task.
 - `espp::DesktopService` — one `Desktop` as a transport-agnostic
-  [dispatcher](../dispatcher) module (`espp.desktop` v1, module 9 by default;
+  [dispatcher](../dispatcher) module (`espp.desktop` v2, module 9 by default;
   one instance per transport).
 - `espp::ConsoleCapture` — tees stdout / stderr into a byte ring (through a
   write-only VFS device) so an app can show the device log live.
@@ -36,7 +36,7 @@ automatic connects off.
 - [Desktop Component](#desktop-component)
   - [Writing an app](#writing-an-app)
   - [Threading rules](#threading-rules)
-  - [Protocol (module 9, `espp.desktop` v1)](#protocol-module-9-esppdesktop-v1)
+  - [Protocol (module 9, `espp.desktop` v2)](#protocol-module-9-esppdesktop-v2)
   - [Log capture](#log-capture)
   - [Example](#example)
 
@@ -96,7 +96,12 @@ once.
 - The only frame sent from another context is `DesktopService`'s ERROR for a
   malformed request.
 
-## Protocol (module 9, `espp.desktop` v1)
+## Protocol (module 9, `espp.desktop` v2)
+
+Version 2 (negotiated through discovery) differs from the never-released v1
+only in what the host does: it applies `MaxTextBytes` to `TextAppend` the
+way the device does, and it honours the DESKTOP `Snapshot` flag (bit2). The
+message layouts are unchanged (the DESKTOP payload's own `proto` byte stays 1).
 
 Framed with `stream_frame` and routed by `espp::Dispatcher`; requests carry
 the reply flag clear, replies / events set it (type high bit). All multi-byte
diff --git a/components/desktop/example/README.md b/components/desktop/example/README.md
index 2b17e1d87d..7724194370 100644
--- a/components/desktop/example/README.md
+++ b/components/desktop/example/README.md
@@ -5,7 +5,7 @@ registers apps and describes their windows / widgets with `espp::Desktop`;
 the hosted [desktop web app](https://esp-cpp.github.io/espp/apps/desktop.html)
 (`components/desktop/web/desktop.html`) draws and operates them over the
 native USB port, on both the **vendor (WebUSB)** and **CDC (Web Serial)**
-interfaces (`espp.desktop` v1 on module 9 by default). The
+interfaces (`espp.desktop` v2 on module 9 by default). The
 [Device Hub](https://esp-cpp.github.io/espp/apps/dispatcher_hub.html) lists it
 through discovery next to the standard services.
 
diff --git a/components/desktop/include/detail/desktop_protocol.hpp b/components/desktop/include/detail/desktop_protocol.hpp
index c9b131f962..9936d9a8c0 100644
--- a/components/desktop/include/detail/desktop_protocol.hpp
+++ b/components/desktop/include/detail/desktop_protocol.hpp
@@ -3,7 +3,7 @@
 // Wire protocol of espp::DesktopService / espp::Desktop: a browser-rendered
 // windowed desktop (apps, windows, widgets, dialogs, notifications) over the
 // espp stream_frame codec, routed by an espp::Dispatcher on module 9 by
-// default (`espp.desktop` v1 through discovery).
+// default (`espp.desktop` v2 through discovery).
 //
 // This header is deliberately host-buildable (stream_frame.hpp + the standard
 // library only) so the codec is unit-tested on the host
@@ -93,7 +93,14 @@ namespace espp::detail::desktop_protocol {
 inline constexpr uint8_t kModule = 9;
 /// Stable protocol identifier + version advertised through discovery.
 inline constexpr const char *kProtocol = "espp.desktop";
-inline constexpr uint16_t kProtocolVersion = 1;
+/// Negotiated through discovery (ModuleInfo::protocol_version). v2: the host
+/// applies MaxTextBytes to TextAppend the way the device does (an append past
+/// the bound stays an append on the wire) and honours DESKTOP flags bit2
+/// Snapshot (drops its dialogs / unlisted windows on a snapshot). v1 was never
+/// released; a v1 host would keep appending without trimming and could keep
+/// a stale dialog after a resync. The wire layout of every message is the
+/// same, so kDesktopProto (the DESKTOP payload's own version byte) stays 1.
+inline constexpr uint16_t kProtocolVersion = 2;
 /// The `proto` byte at the head of every DESKTOP payload.
 inline constexpr uint8_t kDesktopProto = 1;
 
diff --git a/components/desktop/test/desktop_host_test.cpp b/components/desktop/test/desktop_host_test.cpp
index 027dd93b08..42414b3932 100644
--- a/components/desktop/test/desktop_host_test.cpp
+++ b/components/desktop/test/desktop_host_test.cpp
@@ -463,7 +463,7 @@ static std::vector<Vector> catalogue() {
 }
 
 static const char *kFixtureHeader =
-    "# espp desktop protocol golden vectors (espp.desktop v1, dispatcher module 9).\n"
+    "# espp desktop protocol golden vectors (espp.desktop v2, dispatcher module 9).\n"
     "# Generated by components/desktop/test/desktop_host_test.cpp --gen; edit the\n"
     "# catalogue there, not this file. Shared by the C++ host test (encoders must\n"
     "# reproduce the hex, decoders must reproduce the value) and the web app's node\n"
diff --git a/components/desktop/test/desktop_vectors.txt b/components/desktop/test/desktop_vectors.txt
index c07c4d05f3..c8e19a8ea3 100644
--- a/components/desktop/test/desktop_vectors.txt
+++ b/components/desktop/test/desktop_vectors.txt
@@ -1,4 +1,4 @@
-# espp desktop protocol golden vectors (espp.desktop v1, dispatcher module 9).
+# espp desktop protocol golden vectors (espp.desktop v2, dispatcher module 9).
 # Generated by components/desktop/test/desktop_host_test.cpp --gen; edit the
 # catalogue there, not this file. Shared by the C++ host test (encoders must
 # reproduce the hex, decoders must reproduce the value) and the web app's node
diff --git a/components/desktop/web/desktop.html b/components/desktop/web/desktop.html
index 44ec98ac4c..ca2c9fe4e5 100644
--- a/components/desktop/web/desktop.html
+++ b/components/desktop/web/desktop.html
@@ -6,7 +6,7 @@
   <title>espp Desktop (WebUSB / Web Serial)</title>
 <meta name="description" content="A windowed desktop for an espp device, rendered entirely in the browser from the widget tree the firmware's desktop component streams over WebUSB or Web Serial: apps, windows, widgets, dialogs and notifications.">
 <meta name="espp-category" content="device management">
-<meta name="espp-protocols" content="espp.desktop:1">
+<meta name="espp-protocols" content="espp.desktop:2">
 <meta name="espp-transports" content="webusb webserial">
   <!--
     espp Desktop (WebUSB / Web Serial)
@@ -29,7 +29,7 @@
       [magic u16 = 0x4F54 "OT"][flags u8][module u8][type u8][len u32][payload...][crc32 u32]
     flags bit0 = reply (0 host->device, 1 device->host); bits 4-7 = version 1.
 
-    Desktop protocol (module 9 by default, `espp.desktop` v1):
+    Desktop protocol (module 9 by default, `espp.desktop` v2):
       str8 = [len u8][utf8], str16 = [len u16][utf8], rec = [tag u8][len u16][value]
       host -> device : 0x01 GET_DESKTOP, 0x02 LAUNCH_APP[app u8],
                        0x03 CLOSE_WINDOW[win u16],
@@ -472,7 +472,7 @@ <h1>espp Desktop <span class="muted">(WebUSB / Web Serial)</span></h1>
     // advertised protocol id, then app / name); ?module=N overrides it. The
     // PROTOCOL constants mirror desktop_protocol.hpp kProtocol(Version).
     const DEFAULT_MODULE_DESKTOP = 9;
-    const DESKTOP_PROTOCOL = "espp.desktop", DESKTOP_PROTOCOL_VERSION = 1;
+    const DESKTOP_PROTOCOL = "espp.desktop", DESKTOP_PROTOCOL_VERSION = 2;
     const DESKTOP_IDENT = { protocol: DESKTOP_PROTOCOL, protocolVersion: DESKTOP_PROTOCOL_VERSION, app: "desktop.html", name: "Desktop", fallback: DEFAULT_MODULE_DESKTOP, override: null };
     let moduleDesktop = DEFAULT_MODULE_DESKTOP;   // adopted by adoptModules() before the first request
     // True once adoptModules() has run for this connection: every send path
diff --git a/components/desktop/web/test/desktop_codec_test.js b/components/desktop/web/test/desktop_codec_test.js
index 008efa5411..7ce8a1b400 100644
--- a/components/desktop/web/test/desktop_codec_test.js
+++ b/components/desktop/web/test/desktop_codec_test.js
@@ -298,11 +298,11 @@ test("ansiSplit: SGR colours / attributes, state carried, other escapes dropped"
 test("registry metadata and wiring constants", () => {
   const meta = (name) => { const m = new RegExp('<meta\\s+name="' + name + '"\\s+content="([^"]*)"').exec(html); return m ? m[1] : null; };
   assert.strictEqual(meta("espp-category"), "device management");
-  assert.strictEqual(meta("espp-protocols"), "espp.desktop:1");
+  assert.strictEqual(meta("espp-protocols"), "espp.desktop:2");
   assert.strictEqual(meta("espp-transports"), "webusb webserial");
   assert(/<title>espp Desktop \(WebUSB \/ Web Serial\)<\/title>/.test(html));
   assert(html.includes('const DEFAULT_MODULE_DESKTOP = 9;'));
-  assert(html.includes('const DESKTOP_PROTOCOL = "espp.desktop", DESKTOP_PROTOCOL_VERSION = 1;'));
+  assert(html.includes('const DESKTOP_PROTOCOL = "espp.desktop", DESKTOP_PROTOCOL_VERSION = 2;'));
   assert(html.includes('let moduleDesktop = DEFAULT_MODULE_DESKTOP;'));
   assert.strictEqual(P.DESKTOP_MAX_PAYLOAD_CAP, 4081);
   assert.strictEqual(P.DESKTOP_HAS_SNAPSHOT, 0x01); assert.strictEqual(P.DESKTOP_WINDOW_LIST_COMPLETE, 0x02);
diff --git a/components/dispatcher/README.md b/components/dispatcher/README.md
index 6cc6da2ae2..bd44683c24 100644
--- a/components/dispatcher/README.md
+++ b/components/dispatcher/README.md
@@ -31,7 +31,7 @@ protocols and examples use these ids by default:
 | 6         | MCP266                                          | `espp.mcp266` v1              |
 | 7         | System info / reboot (`espp::SystemService`)    | `espp.system` v1              |
 | 8         | Heap / task monitor (`espp::MonitorService`)    | `espp.monitor` v1             |
-| 9         | Windowed desktop (`espp::DesktopService`)       | `espp.desktop` v1             |
+| 9         | Windowed desktop (`espp::DesktopService`)       | `espp.desktop` v2             |
 | 0xF0–0xFE | reserved (meta)                                 | —                             |
 | 0xFF      | capability discovery                            | —                             |
 
diff --git a/doc/en/desktop/desktop.rst b/doc/en/desktop/desktop.rst
index bdb4f6ea9d..e8caf34a7b 100644
--- a/doc/en/desktop/desktop.rst
+++ b/doc/en/desktop/desktop.rst
@@ -31,7 +31,7 @@ maximizable, centered, pinned, wants-geometry) and a geometry the browser may
 override with what the user last chose (remembered per app and title).
 
 The `DesktopService` class serves one ``Desktop`` over **any byte stream** as
-a :doc:`dispatcher <../dispatcher/dispatcher>` module (``espp.desktop`` v1,
+a :doc:`dispatcher <../dispatcher/dispatcher>` module (``espp.desktop`` v2,
 module id 9 by default; one instance per transport). It only decodes and
 validates: a malformed request is answered with ``ERROR``, everything else is
 handed to the desktop and handled — replied to, and its events broadcast — on
diff --git a/doc/en/dispatcher/custom_modules.rst b/doc/en/dispatcher/custom_modules.rst
index 1f6a3b177c..777f2da04f 100644
--- a/doc/en/dispatcher/custom_modules.rst
+++ b/doc/en/dispatcher/custom_modules.rst
@@ -68,7 +68,7 @@ Module id  Protocol                                                  Protocol id
 6          MCP266 motor-controller console (``espp::Mcp266Service``) ``espp.mcp266`` v1
 7          System info / reboot control (``espp::SystemService``)    ``espp.system`` v1
 8          Heap / task monitor (``espp::MonitorService``)            ``espp.monitor`` v1
-9          Windowed desktop (``espp::DesktopService``)               ``espp.desktop`` v1
+9          Windowed desktop (``espp::DesktopService``)               ``espp.desktop`` v2
 0xF0-0xFE  reserved for dispatcher / meta use
 0xFF       capability discovery
 =========  ========================================================  ==================================
diff --git a/doc/en/dispatcher/dispatcher.rst b/doc/en/dispatcher/dispatcher.rst
index 394299494b..e49357931d 100644
--- a/doc/en/dispatcher/dispatcher.rst
+++ b/doc/en/dispatcher/dispatcher.rst
@@ -30,7 +30,7 @@ Module id  Protocol                                        Protocol id (discover
 6          MCP266 console                                  ``espp.mcp266`` v1
 7          System info / reboot                            ``espp.system`` v1
 8          Heap / task monitor                             ``espp.monitor`` v1
-9          Windowed desktop                                ``espp.desktop`` v1
+9          Windowed desktop                                ``espp.desktop`` v2
 0xF0-0xFE  reserved (meta)
 0xFF       capability discovery
 =========  ==============================================  ===============================